1# The OSKAR Python Interface
2
3The OSKAR package has been designed to produce simulated visibility data from
4radio telescopes containing aperture arrays. The software is written
5mainly in C and offers GPU acceleration using CUDA or OpenCL. The Python
6bindings to OSKAR make it easy to run simulations using Python scripts.
7
8Documentation for the OSKAR Python bindings can be found by following the link
9on the [simulation tools page](https://developer.skatelescope.org/projects/sim-tools/en/latest/)
10of the SKA Developer Portal.
11
12
13## Installation
14
15### Linux and macOS
16
17 - Make sure you have a working Python environment
18   (including `pip` and `numpy`), C and C++ compilers.
19     - On macOS, the compilers are part of XCode, which is in the App Store.
20
21
22 - Make sure OSKAR has been installed.
23     - On macOS, you can drag the [pre-built package](https://github.com/OxfordSKA/OSKAR/releases) `OSKAR.app` to `/Applications`
24
25
26 - Open a Terminal.
27
28
29 - (Not usually required) If OSKAR is installed in a non-standard location,
30   edit the paths in `setup.cfg` or temporarily set the two environment
31   variables:
32
33```bash
34export OSKAR_INC_DIR=/path/to/oskar/include/folder
35export OSKAR_LIB_DIR=/path/to/oskar/lib
36```
37
38 - Install the Python interface with:
39
40```bash
41pip install --user 'git+https://github.com/OxfordSKA/OSKAR.git@master#egg=oskarpy&subdirectory=python'
42```
43
44 - The `--user` flag is optional, but you may need root permission without it.
45
46### Windows
47
48 - Make sure you have a working [Python](https://www.python.org/downloads/windows/)
49   environment (including `pip` and `numpy`),
50   and [Visual Studio Community C and C++ compiler](https://visualstudio.microsoft.com/vs/community/).
51     - You will need to make sure that Python is added to the PATH environment
52       variable when it is installed.
53     - These steps also work with the Anaconda Python distribution,
54       but Anaconda is not required.
55
56
57 - Make sure OSKAR has been installed using the [pre-built package](https://github.com/OxfordSKA/OSKAR/releases).
58     - In the installer, you will need to select the option **Add OSKAR to the PATH**,
59       and install all optional components (headers and libraries).
60
61
62 - Open a Command Prompt (or an Anaconda Prompt, if using Anaconda).
63
64
65 - (Not usually required) If OSKAR is installed in a non-standard location,
66   edit the paths in `setup.cfg` or temporarily set the two environment
67   variables:
68
69```
70set OSKAR_INC_DIR=C:\path\to\oskar\include\folder
71set OSKAR_LIB_DIR=C:\path\to\oskar\lib
72```
73
74 - Install the Python interface with:
75
76```
77pip install "git+https://github.com/OxfordSKA/OSKAR.git@master#egg=oskarpy&subdirectory=python"
78```
79
80### Using Pipenv
81
82This works also with [Pipenv](https://docs.pipenv.org)
83(but make sure the above environment variables are set first, if necessary):
84
85```bash
86pipenv install -e 'git+https://github.com/OxfordSKA/OSKAR.git@master#egg=oskarpy&subdirectory=python'
87```
88
89
90## Uninstallation
91
92After installation using the steps above, the OSKAR Python interface can
93be uninstalled using:
94
95```bash
96pip uninstall oskarpy
97```
98
99(This does not uninstall OSKAR itself, only the Python interface to it.)
100
101