.. This file is part of Sympathy for Data.
.. Copyright (c) 2017-2019 Combine Control Systems AB
..
.. Sympathy for Data is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, version 3 of the License.
..
.. Sympathy for Data is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with Sympathy for Data.  If not, see <http://www.gnu.org/licenses/>.

.. _installation:

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


Self-contained installer
------------------------

.. note::
  Installers are offered as a service to users of our Enterprise Edition. For
  more information see https://www.sympathyfordata.com/.

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 full-fledged Python environment specifically tailored for data
science.

After downloading the installer, simply run it and follow the instructions.
This will install Sympathy. Once done you can start Sympathy from the start
menu and you are all set to go.


Manual install
--------------

If you prefer to install Sympathy manually instead of using our installer there
are a few steps required:

1. Install python
2. Create a virtual environment
3. Install dependencies
4. Install Sympathy from a local wheel file


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

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

If you already have a suitable installation of python, you can skip this
step.

Windows
'''''''

On Windows you have to download and install an appropriate version of `Python
<https://www.python.org/downloads/>`__. That is, the Windows installer (64-bit)
for a supported version. Make sure to include pip while installing.

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 <http://www.macports.org>`__.  Before continuing,
it is recommended to update the package definitions.

.. code-block:: bash

    sudo port selfupdate

Then install the dependencies.

.. code-block:: bash

    sudo port install python310 unixODBC

Linux
'''''

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

First update your package definitions and update outdated packages.

.. code-block:: bash

    sudo apt-get update
    sudo apt-get dist-upgrade

Then install the required prerequisites

.. code-block:: bash

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


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

Though not strictly necessary, we *strongly* recommend that you use a virtual
environment rather than installing in a system level python installation!

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

Windows
'''''''

.. code-block:: bat

    <python> -m venv <env-sympathy>
    cd <env-sympathy>\Scripts
    activate.bat
    pip install -U pip setuptools wheel

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

.. code-block:: bash

    <python> -m venv <env-sympathy>
    source <env-sympathy>/bin/activate
    pip install -U pip setuptools wheel


3. Install dependencies
~~~~~~~~~~~~~~~~~~~~~~~
To ensure compatibility we suggest that you install the same versions of all
the dependencies for Sympathy that are used in the self-contained installer.
These requirements can be downloaded `here
<https://www.sympathyfordata.com/download/requirements-5.0.0.txt>`__
for Sympathy version 5. After downloading the file run the following command in
your virtual environment:

.. code-block:: bash

    pip install -r requirements-5.0.0.txt

Skipping this step will install the latest versions of all dependencies instead.
While this *might* work fine, there is no way for us to guarantee this. If you
run into trouble when trying to run Sympathy in custom environment you can try
to downgrade packages. Again, to be completely certain of using supported
versions, install the requirements as detailed above before installing Sympathy.


4. Install Sympathy from local wheel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you need to make a custom installation from a wheel file, please contact us.

With the desired python environment active, run the following to install
Sympathy (replace <version> with the version that you have downloaded):

.. code-block:: bash

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

You are now ready to run Sympathy for Data!


Running Sympathy
~~~~~~~~~~~~~~~~

In order to run Sympathy using python, first make sure that the virtual
environment used in the installation steps is active. You can run Sympathy
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 additional executables for your virtual
environment. On Windows these are typically located in a folder called
"Scripts", and on Unix in a folder called "bin". These executables run Sympathy
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.

Some small functionality (like drag and dropping flows to open them) depends on
pyobjc being installed as well, on Mac. This pip package adds a lot of
dependencies however, so it is left to the user to decide if this is wanted:

.. code-block:: bash

    pip install pyobjc  # optional

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 (or the package manager that is
preferred by your distribution) to install missing libraries.

.. code-block:: bash

    sudo apt-get install unixodbc-dev


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

These optional features can be installed to extend the functionality of
Sympathy for Data. See the outlined sections for more information:

.. toctree::
   :maxdepth: 1

   graphviz.rst