.. This file is part of Sympathy for Data.
.. Copyright (c) 2017-2019 Combine Control Systems AB
..
.. SYMPATHY FOR DATA COMMERCIAL LICENSE
.. You should have received a link to the License with Sympathy for Data.

.. _installation:

Installation from wheel
=======================

Our pre-built executable installers are the easiest way to start using Sympathy
for Data on Windows. They contain everything needed to run Sympathy for Data
including a fully-featured Python environment specifically tailored for data
analysis.

The instructions below are for cases when you instead want to install Sympathy
for Data from a wheel file.

If you prefer to install Sympathy manually from a wheel file there are a few
steps required:

1. Install python
2. Create a virtual environment
3. Install Sympathy from wheel


1. Install Python
~~~~~~~~~~~~~~~~~

Sympathy for Data currently supports Python 3.11 and 3.12. While it may
also run on newer minor versions, it will not run correctly on older versions.

Windows
'''''''

On Windows you can download and install an appropriate version of Python
from `python.org`_.

.. _`python.org`: https://www.python.org/downloads/

MacOS
'''''

These instructions are written for MacOS X 11.7.6 using MacPorts.

Start by installing XCode from the App Store (that will download an XCode
installer, so this is a two-stage process).

.. code-block:: bash

    sudo xcode-select --install
    sudo xcodebuild -license

Download and install MacPorts_.  Before continuing,
it is recommended to update the package definitions.

.. _MacPorts: https://www.macports.org

.. code-block:: bash

    sudo port selfupdate

Then install the dependencies.

.. code-block:: bash

    sudo port install python310 unixODBC

Linux
'''''

The current version of Sympathy for Data officially supports Ubuntu 24.04 LTS.
To install on other versions (and distributions), you may have to adjust the
steps.

Start by installing the required prerequisites

.. code-block:: bash

    sudo apt install build-essential python3-dev python3-venv unixodbc-dev


2. Create virtual environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Navigate to a directory in which you want to create the virtual environment. In
the following instructions, replace <sympathy-env> with the name that you want
to use for the virtual environment.

Windows
'''''''

.. code-block:: bat

    py -m venv <sympathy-env>
    <sympathy-env>\Scripts\activate.bat

MacOS/Linux
'''''''''''

.. code-block:: bash

    python -m venv <sympathy-env>
    source <sympathy-env>/bin/activate


3. Install Sympathy from wheel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

With the desired python environment active, run the following to install
Sympathy (replace <sympathy-filename> with the filename of your wheel file):

.. code-block:: bash

    python -m pip install <sympathy-filename>.whl
    python -m sympathy install

You are now ready to run Sympathy for Data!


Running Sympathy for Data
~~~~~~~~~~~~~~~~~~~~~~~~~

You are now ready to start Sympathy for Data either with a GUI (first command
below), or for data processing applications in head-less mode (second command).
For a more comprehensive list of commands and options, see
:ref:`launch_options`.

.. code-block:: bash

  python -m sympathy gui
  python -m sympathy cli <my-workflow>

Installing Sympathy also creates an additional executable for your virtual
environment. On Windows this is typically located in a folder called "Scripts",
and on Unix in a folder called "bin". This executable runs Sympathy for Data in
the same way as above but does not require the virtual environment to be
activated beforehand.

.. code-block:: bash

  sympathy gui
  sympathy cli <my-workflow>

Troubleshooting
~~~~~~~~~~~~~~~

If you see any text in red during the execution of pip, this would typically
mean that some library is missing in your system. See the section for your OS
below for instructions on how to install packages.

MacOS
'''''

For example, if you get an error while installing pyodbc, that typically means
you need to install a package named unixODBC. Use port to install missing
libraries.

Linux
'''''

For example, if you get an error while installing pyodbc, that typically means
you need to install a package named unixodbc-dev (or unixODBC-devel, the names
tend to vary across Linux distributions). Use apt to install missing libraries.

.. code-block:: bash

    sudo apt install unixodbc-dev


Optional features
-----------------

Some nodes require extra third-party python packages to be installed to be able
to run. This will be done automatically when such a node is executed for the
first time. If you prefer to install such extra python packages ahead of time,
you can do so by running:

.. code-block:: bash

    python -m pip install <sympathy-filename>.whl[all]

See also :ref:`graphviz`.