.. _installation:

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

WindKit is distributed as both `pypi <https://pypi.org>`__ and `conda <https://docs.conda.io/en/latest/>`__ packages. However, due to dependencies 
on several GIS utilities (`GeoPandas <https://geopandas.org>`__, `Rasterio <https://rasterio.readthedocs.io>`__), 
which depend on large C based libraries (`GEOS <https://geos.osgeo.org/>`__, `GDAL <https://www.gdal.org/>`__, `PROJ <https://proj.org/>`__), 
we recommend installing using the conda packages whenever possible.


Recommended Installation
------------------------

We strongly recommend using a modern, fast package manager from the conda ecosystem like `mamba <https://mamba.readthedocs.io/en/latest/>`__ or 
`pixi <https://pixi.sh/>`__. These tools provide significant speed improvements and better dependency 
resolution compared to the classic `conda <https://anaconda.org/anaconda/conda>`__ client.

Using Mamba (via Miniforge)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`Mamba <https://mamba.readthedocs.io/en/latest/>`__ is a fast, drop-in replacement for `conda <https://https://anaconda.org/anaconda/conda>`__. 
We recommend installing it via the 
`Miniforge <https://github.com/conda-forge/miniforge>`__ installers, which pre-configure the essential `conda-forge <https://conda-forge.org/>`__ channel.

1. **Install Miniforge.** Follow the instructions on their `GitHub page <https://github.com/conda-forge/miniforge>`__.

2. **Create an environment and install WindKit.** Create a new, isolated environment for your project. This is a best practice to avoid dependency conflicts. 
The following command will create an environment named ``wk-env`` with WindKit, explicitly using the required channels.

  .. code-block:: shell

    mamba create -n wk-env windkit -c https://conda.windenergy.dtu.dk/channel/open/ -c conda-forge

3. **Activate the environment.**

  .. code-block:: shell

    mamba activate wk-env

  .. note::
    If you prefer to configure channels globally first, you can run the following commands and then omit the ``-c`` flags from the ``mamba create`` command.

    .. code-block:: shell

      mamba config --add channels https://conda.windenergy.dtu.dk/channel/open/
      mamba config --add channels conda-forge


Using Pixi
~~~~~~~~~~

`Pixi <https://pixi.sh/>`__ is a modern project and package manager built on the conda ecosystem. It uses a ``pixi.toml`` file to manage project dependencies, 
similar to ``pyproject.toml``, and is great for creating reproducible project environments.

1. **Install Pixi.** Follow the official `installation guide <https://pixi.sh/latest/installation/>`__.

2. **Initialize a new project.** In your project directory, run:

  .. code-block:: shell

    pixi init

3. **Add WindKit as a dependency.** This command adds the required channels and the :ref:`windkit` package to your ``pixi.toml`` file and installs it into the project's environment.

  .. code-block:: shell

    pixi add --channel https://conda.windenergy.dtu.dk/channel/open/ --channel conda-forge windkit

4. **Use the environment.** You can now run commands within the managed environment. For example, to start a Python interpreter or run a script:

  .. code-block:: shell

    pixi run python
    pixi run python my_script.py

To open a shell within the activated environment, run ``pixi shell``.


Legacy Conda Installation
-------------------------
If you prefer to use the classic `conda <https://https://anaconda.org/anaconda/conda>`__ client, you can follow these steps. 
Note that dependency resolution may be significantly slower.

1. **Install a conda distribution.** If you don't have one, we recommend `Miniforge <https://github.com/conda-forge/miniforge>`__.

2. **Configure channels.** Open a conda-enabled terminal (e.g., "Anaconda Prompt" on Windows) and add the necessary channels.

  .. code-block:: shell

    conda config --add channels https://conda.windenergy.dtu.dk/channel/open/
    conda config --add channels conda-forge

3. **Create an environment.**

  .. code-block:: shell

    conda create -n <env_name> windkit

4. **Activate the environment.**

  .. code-block:: shell

    conda activate <env_name>


Alternative: PyPI Installation
------------------------------

.. warning::
  Installing WindKit from PyPI using ``pip``, ``uv``, or other package managers can be significantly more complex than using conda. 
  This is because PyPI installers do not manage the non-Python, C-based libraries that WindKit's dependencies (like GeoPandas and Rasterio) rely on 
  (e.g., GDAL, GEOS, PROJ).

  You are responsible for installing these system-level dependencies yourself before installing WindKit. For this reason, we **strongly recommend** 
  the conda-based installation methods for a much smoother experience.

If you are an experienced user and have the necessary system libraries installed, you can use a PyPI-based installer. It is essential to always 
work within a virtual environment.

Using pip 
~~~~~~~~~~~~~~~~~~~~~

This is the standard approach using pip.

1.  **Install WindKit.**
    To install the base package:

    .. code-block:: shell

      pip install windkit

    To include optional dependencies:

    .. code-block:: shell

      pip install windkit[plots,data_apis,performance]

.. note:: 
  
  We recommend using a virtual environment to avoid conflicts with other Python packages. You can create one using `venv <https://docs.python.org/3/library/venv.html>`__ or `virtualenv <https://virtualenv.pypa.io/en/latest/>`__.

Using uv
~~~~~~~~

`uv <https://github.com/astral-sh/uv>`__ is an extremely fast Python package installer and resolver, designed as a drop-in replacement for ``pip`` and ``venv``.

1. **Install uv.** Follow the official `installation guide <https://astral.sh/docs/uv#installation>`__.

2. **Create and activate a virtual environment.** ``uv`` can create and manage virtual environments.

    .. code-block:: shell

      # Create the virtual environment
      uv venv

      # Activate the environment (same as with venv)
      # On macOS/Linux
      source .venv/bin/activate
      # On Windows
      .venv\Scripts\activate

3. **Install WindKit.** Use ``uv pip`` to install packages into the activated environment.

    To install the base package:

    .. code-block:: shell

      uv pip install windkit

    To include optional dependencies:

    .. code-block:: shell

      uv pip install windkit[plots,data_apis,performance]

.. note::
  If you encounter installation errors, they are almost certainly related to the missing C library dependencies. 
  Please consult the detailed installation guides for `GeoPandas <https://geopandas.org/en/stable/getting_started/install.html>`__ and 
  `Rasterio <https://rasterio.readthedocs.io/en/latest/installation.html>`__ for platform-specific instructions.


Dependencies
--------------

Required dependencies:

  - `platformdirs <https://platformdirs.readthedocs.io>`__
  - `pydantic <https://docs.pydantic.dev/latest>`__
  - `pydantic-settings <https://docs.pydantic.dev/latest/concepts/pydantic_settings>`__
  - `geopandas <https://geopandas.org>`__ (version 0.8 or later)
  - `lxml <https://lxml.de/>`__
  - `netcdf4 <https://unidata.github.io/netcdf4-python/>`__
  - `numpy <http://www.numpy.org/>`__
  - `packaging <https://packaging.pypa.io/en/latest/>`__ (Provides version handling)
  - `pandas <http://pandas.pydata.org/>`__ (version 1 or later)
  - `pyproj <https://github.com/pyproj4/pyproj>`__ (version 2.2.2 or later)
  - `rasterio <https://rasterio.readthedocs.io>`__
  - `rtree <https://github.com/Toblerity/rtree>`__
  - `scipy <https://scipy.org/>`__
  - `shapely <https://shapely.readthedocs.io/en/stable/manual.html>`__
  - `xarray <xarray.pydata.org/>`__
  - `requests <https://requests.readthedocs.io/en/latest/>`__

Plotting dependencies (optional: ``plotting``):
  - `kaleido <https://pypi.org/project/kaleido/>`__ (Used to export plotly images to file)
  - `matplotlib <https://matplotlib.org/>`__
  - `plotly <https://plotly.com/python/>`__

Data API dependencies (optional: ``data_api``):
  - `earthengine-api <https://developers.google.com/earth-engine/guides/python_install>`__ (Google Earth Engine: provides access to geospatial data from google. Non-commercial uses only.)
  - `planetary-computer <https://pypi.org/project/planetary-computer/>`_ (Microsoft Planetary Computer: provides access to geospatial and atmospheric data from Microsoft. Terms of use apply.)
  - `pystac-client <https://pystac-client.readthedocs.io/en/stable/>`_ (Used to access SpatioTemporal Asset Catalogs (STAC) data on Microsofts Planetary Computer)
  - `fsspec <https://filesystem-spec.readthedocs.io/en/latest/>`_ (Used for accessing ERA5 data from the Planetary Computer)
  - `adlfs <https://pypi.org/project/adlfs/>`_ (Used for accessing ERA5 data from the Planetary Computer)

Performance dependecies (optionaL: ``performance``):
  - `numba <https://numba.pydata.org/>`__ (Used to speed up some functions)