Installation

Note

Note that PAMTRA finally supports Python 2.7 and Python 3.6 - 3.8 as of August 2020.

Quickstart: Virtual Machine

This is the recommended way to test the model. A virtual machine is provided which makes the installation 100% automatic. You have to install the following software in order to run the virtual machine with PAMTRA on your computer:

When using Mac OS or Windows, download the installation routines frotm the websites, on Linux use

sudo apt-get install virtualbox vagrant

Change the directory to ´tools/virtual_machine in the terminal (on linux and mac os cd tools/virtual_machine) and type

vagrant up

This command will configure the virtual machine based on the information provided in Vagrantfile. It will download a lot of data, so don’t do that with a bad internet connection and make sure you have some GB space on your hard disk.

When the machine is running, you can connect to it with

vagrant ssh

in order to have terminal access. When you are done, do

vagrant halt

from the host computer to turn the virtual machine off. You can start with

vagrant up

again. To delete the virtual machine and its containing data, do

vagrant destroy

from the host. Note that the shared folder in the virtual machine’s home directory links to the virtual_machine of the host system. I.e. you can use that directory for file exchange and for editing files with you favorite editor.

When the virtual machine is running, you should be able to access a jupyter notebook at http://localhost:8880 from your host machine. The password is jupyter. All examples in shared/examples should work and produce a plot. Jupyter notebook is a python environment, but can be used with other languages, too. More information at http://jupyter.org. The default python version is 3.8, but 2.7 is installed as well, PAMTRA is installed for both environments. From the command line, you can switch with

conda activate py27

to python 2.7, and go back to 3.8 with

conda activate base

If you miss any of your favorite python packages, do

pip install missing_module_name

Make sure that the correct python version is selected with `conda activate `. When using conda instaed of pip, make sure that libgfortran is not installed by conda. For some reason, PAMTRA does not like conda’s libgfortran on Linux.

The update.sh script in the shared folder can be used to update the PAMTRA model and the data provided on the FTP server if they get updated.

Install Dependencies

Ubuntu 20.04

On a fresh Ubuntu 20.04 installation, the following packages need to be installed to get PAMTRA from the github repository and to compile and install PAMTRA:

sudo apt install git gfortran libnetcdf-dev libnetcdff-dev liblapack-dev libfftw3-dev python3-dev python3-numpy

Replace python3-X with python-X when using Python 2.7 instead of 3.

Although not required for compilation and installation, to use PAMTRA, some additional python packages need to be installed on your system or python environemnt.:

sudo apt install python3-matplotlib python3-pandas python3-scipy python3-netcdf4

Warning

As of August 2020, do NOT use conda for Ubuntu because the provided libgfortran library does not work with PAMTRA.

On Ubunut systems (and probably as well other linux OS), there is an issue with openblas and competeting insterests of multiple parallel jobs. To avoid this, set the environment variable:

export OPENBLAS_NUM_THREADS=1

before calling python.

Now, follow - Get model from git repository

Mac OS X

On Mac OS X, it is recommended to use brew (http://brew.sh) to install gfortran (via gcc) and netcdf

brew install gcc
brew install fftw
brew install netcdf

For the Python version, it is recommended not to use OS X’s default python version, but to install an independent one, e.g. with brew or conda (https://www.continuum.io/downloads). In addition, the following packages are required:

pip install pandas numpy scipy matplotlib netcdf4

or

conda install pandas numpy scipy matplotlib netcdf4

Now, follow - Get model from git repository

Microsoft Windows 10 with windows subsystem for linux

To install windows subsystem for linux follow the instructions on

https://docs.microsoft.com/de-de/windows/wsl/install-win10

Install ubuntu 16.04 from the Microsoft Store. After configuration, you need to install additional packages within the ubuntu linux system

sudo apt update
sudo apt install git make

Afterwards, follow the instructions for Ubuntu.

Get model from git repository

The version control system git (http://git-scm.com/) is used to keep track of the code. Get a copy of the model with:

git clone --recursive https://github.com/igmk/pamtra

The very basics of git can be found here https://try.github.io/levels/1/challenges/1 . “–recursive” is required because git submodules are used.

Build PAMTRA

Simply type

make

to build PAMTRA and pyPamtra. You can build them also separately with

make pamtra

and

make py

Usually superuser permission are required to install python routines. To avoid that a local python library folder is used in ~/lib/python/ and this path has to be added to the $PYTHONPATH variable of your shell (assuming you are using Ubuntu and bash)

echo 'export PYTHONPATH=$PYTHONPATH:$HOME/lib/python' >> ~/.bashrc

For Mac OS X, do

echo 'export PYTHONPATH=$PYTHONPATH:$HOME/lib/python' >> ~/.bash_profile

Then, the python routines can be installed with

make pyinstall

To run pyPamtra with python3, F2PY=f2py3 needs t be appended to make and make pyinstall.

Download data

Although PAMTRA can be used without additional data by simply setting the data path to an empty directory,

echo 'export PAMTRA_DATADIR=""' >> ~/.bashrc

it is recommended that you download the data. The data includes the land surface emissivity maps and some scattering databases. They can be found on the servers of University of Cologne

Download and unpack the data:

wget -q -O data.tar.bz2 https://uni-koeln.sciebo.de/s/As5fqDdPCOx4JbS/download
tar xjf data.tar.bz2
rm data.tar.bz2

and set the $PAMTRA_DATADIR variables

echo 'export PAMTRA_DATADIR="wherever/it/is/"' >> ~/.bashrc

To start using pyPamtra, you have to open a new bash session or source the ~/.bashrc

source ~/.bashrc

Start PAMTRA

Warning

When running on ubuntu 20.04 (and maybe above) one needs to set export OPENBLAS_NUM_THREADS=1 before starting python. THis is because ubuntu 20.04 is running a BLAS library that is not thread save.

You can start using pyPamtra in python with

import pyPamtra

Build documentation

Several package have to be installed to be able to build the documentation. The documentation is build using sphinx

sudo apt install python-sphinx

In addition, the numpydoc is required

sudo apt install python-numpydoc

If not available try

sudo easy_install numpydoc

Eventually, you can build the documentation by using the Makefile in the PAMTRA main directory with

make htmldoc