.. highlight:: shell

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

Stable release (PyPI)
---------------------
To install carbatpy, run:

.. code-block:: console

   $ pip install carbatpy

This is the preferred method, as it installs the most recent stable release.

If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.

.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/

REFPROP (mandatory)
-------------------
carbatpy requires **REFPROP (NIST)** and a valid license. Without REFPROP the package
is not useful for typical workflows.

The installation is expected in the following folder:

* ``C:\Program Files (x86)\REFPROP``

If you deviate from these locations, set/adapt the system environment variables:

* ``RPPREFIX``  (path to the REFPROP installation)

Optional: REFPROPLibraryManager
-------------------------------
Using the REFPROPLibraryManager is optional, but can be much faster and is thread-safe.

The REFPROPLibraryManager needs to be downloaded and build via https://github.com/usnistgov/REFPROP-manager
The path to the built REFMAN.dll needs to be set as user variable named: REFPROPLibraryManager.

* ``REFPROPLibraryManager``  (path to the REFMAN.dll)


Optional: TREND
---------------
Support for TREND is available as an optional feature and must be enabled explicitly
in the configuration. Please refer to the TREND6 documentation for installation (Manual -> 5 Using TREND in PYTHON).
Once downloaded, navigate to the TREND6/python folder, then use command:

.. code-block:: console

   $ pip install .

Optional: machine models (SPP 2403 / spp-machines)
--------------------------------------------------
Detailed machine models are provided via a separate add-on package (e.g. ``spp-machines``).
If installed, it can be selected explicitly in relevant functions. The add-on is developed
and maintained separately and may be available on request (license conditions may apply).

From sources (Git)
------------------
The sources for carbatpy can be downloaded from the `Gitlab repo`_.

Clone the repository:

.. code-block:: console

   $ git clone https://git.uni-due.de/spp-2403/td-ude/carbatpy.git
   $ cd carbatpy

Install using pip (recommended for source installs):

.. code-block:: console

   $ pip install .

For development (editable install):

.. code-block:: console

   $ pip install -e .

If you use Poetry:

.. code-block:: console

   $ poetry install

Environment variables (optional)
--------------------------------
You may set the following environment variables:

* ``CARBATPY_BASE_DIR``: base directory where your carbatpy project/code resides
* ``CARBATPY_RES_DIR``: default directory for storing results

On Windows:
Environment Properties → Environment Variables → System variables → New

.. _Gitlab repo: https://git.uni-due.de/spp-2403/td-ude/carbatpy