Ctrl+K

Installation#

Requirements#

pycraf has the following strict requirements:

There are a few optional packages, which are necessary for some functionality:

Older versions of these packages may work, but no support will be provided.

Installing pycraf#

There are various ways to install pycraf. The easiest and cleanest approach would be to use the Anaconda/Miniconda Python distribution, because it allows to download a binary package, which is well-tested against all dependency packages.

Using Anaconda#

After installing Anaconda, one can run the conda package manager:

conda install pycraf -c conda-forge

Note

pycraf and many other packages are not in default channel of Anaconda. So you have to use the conda-forge channel.

Note

It is always a good idea to keep different projects separated and conda allows to easily create virtual environments. To set one up for pycraf:

conda create -n pycraf-env -c conda-forge python=3.9 pycraf

and to use it:

conda activate pycraf-env

Ideally, one would install all dependencies together with pycraf:

conda create -n pycraf-env -c conda-forge python=3.11 astropy cython h5py matplotlib numpy pycraf 'pyproj>=2.6' pytest pytest-remotedata rasterio scipy 'sgp4>2'

Using pip#

To install pycraf with pip, simply run

pip install pycraf

Note

You may need a C compiler (gcc) with OpenMP support to be installed for the installation to succeed.

Note

Use the --no-deps flag if you already have dependency packages installed, since otherwise pip will sometimes try to “help” you by upgrading your installation, which may not always be desired.

Note

If you get a PermissionError this means that you do not have the required administrative access to install new packages to your Python installation. In this case you may consider using the --user option to install the package into your home directory. You can read more about how to do this in the pip documentation. Better would be to use virtual environments, e.g., base on pipenv.

However, we recommend to use a Anaconda, especially, if you are on Windows.

Do not install pycraf or other third-party packages as Administrator/Root unless you are fully aware of the risks.

Installation from source#

Linux#

There are two options, if you want to build pycraf from sources. Either, you install the tar-ball (*.tar.gz file) from PyPI and extract it to the directory of your choice, or, if you always want to stay up-to-date, clone the git repository:

git clone https://github.com/bwinkel/pycraf

Then go into the pycraf source directory and run:

python -m pip install .

Again, consider the --user option or even better use a python distribution such as Anaconda to avoid messing up the system-wide Python installation.

Note

On Anaconda, the following would install all packages needed for properly working with the sources:

conda create -n pycraf3.10dev python=3.10 'astropy>=5' build cartopy
cython extension-helpers ffmpeg fiona geopandas h5py imagemagick ipdb
ipykernel ipywidgets "matplotlib>=3.3" "numpy==1.21.6" openpyxl osmnx
pandas pip "pyproj>=3" "pyqt>=5.11" pytest pytest-astropy
pytest-doctestplus pytest-qt pytest-remotedata rasterio reproject
scipy setuptools setuptools-scm "sgp4>2" shapely sphinx
sphinx-astropy tqdm twine wheel

Windows#

If you are desperate, you can install pycraf from source even on Windows. You’ll need to install a suitable C-compiler; <see here <https://wiki.python.org/moin/WindowsCompilers>`__. The pycraf package needs Python 3.9 or later, which means VC++ Version 14 or later is mandatory. The easiest way to obtain it, is by installing the Build Tools For Visual Studio. Once installed and if all dependencies are there, the standard

python -m pip install .

should work.

Note

pycraf uses setuptools-scm for automatic version numbering (based on the git hash). For this, git needs to be available in the terminal. (On Anaconda, it can be installed from conda-forge.)

MacOS#

Installation on MacOS can be a bit tricky, because the standard C compiler does not support OpenMP. We provide wheels on PyPI, such that you can

pip install pycraf

however, you need to have the LLVM C compiler (see below), otherwise you’ll likely get an error message that a library (such as “libgomp”) is not found, when you import pycraf in Python.

Also, if you want to install from source, you must have a C compiler. There are basically two options, using LLVM or the gcc suite. The recipe below is likely outdated heavily, but we currently don’t have access to a MacOS machine. You may be able to adapt (if you’re successful, let us know).

LLVM#
brew update
brew install llvm

export CC="/usr/local/opt/llvm/bin/clang"
export LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

Then follow the instructions in Installation from source.

gcc#
brew install gcc6  # or gcc7
brew link --overwrite gcc@6  # or gcc@7

Then follow the instructions in Installation from source.

Note

The MacOS wheel, which we provide on PyPI (for pip installation) was built using LLVM. So it may happen that you run into binary incompatibilities if you use a different compiler suite on your computer. In such cases it may be necessary to build pycraf from source using your own compiler. Sometimes even different compiler versions (e.g. gcc 6.3 instead of gcc 6.4) can lead to problems. Please write a ticket, if you run into trouble.

Note

Again, if you’re on Anaconda, things get (often) much simpler. One only needs to install the conda-forge compiler packages, before pip-installing:

conda install -c conda-forge compilers llvm-openmp

Testing an installed pycraf#

The easiest way to test if your installed version of pycraf is running correctly, is to use the test() function:

import pycraf
pycraf.test()

To run the tests for one sub-package, e.g., conversions, only:

import pycraf
pycraf.test('conversions')

The tests should run and print out any failures, which you can report at the pycraf issue tracker.

Note

This way of running the tests may not work if you do it in the pycraf source distribution directory.

Note

By default, the test function will skip over tests that require data from the internet. One can include them by:

import pycraf
pycraf.test(remote_data='any')

This will always download SRTM data (few tiles only) to test the auto-download functionality! Do this only, if you can afford the network traffic.

If you prefer testing on the command line and usually work with the source code, you can also manually run the tests using pytest. Install the package with pip and then (not within the project directory!):

pytest -rsx --ignore-glob="*/setup_package.py" --pyargs pycraf

# to run tests from a sub-package
pytest -rsx --ignore-glob="*/setup_package.py" --pyargs pycraf -P conversions

# to run a particular test (uses globbing)
pytest -rsx --ignore-glob="*/setup_package.py" --pyargs pycraf -k wgs84

# include tests, which need to download data (will slow down tests)
pytest -rsx --ignore-glob="*/setup_package.py" --pyargs pycraf --remote-data=any

Likewise, to build the docs (inside project directory!):

sphinx-build docs docs/_build/html -b html

Using SRTM data#

To make full use of the path attenuation calculations provided by pycraf, you will need to use NASA’s Shuttle Radar Topography Mission (SRTM) data for height-profile generation. Please see Working with SRTM data for further details.

On this page
Edit on GitHub
Show Source