Installing PCRaster

Installing binaries

PCRaster is available on conda-forge and can be installed using conda. Supported platforms are Linux, macOS and Windows.

We recommend to download and install Miniconda. The user guide and short reference on conda can be found here. After install you can check which Python versions are supported by PCRaster:

conda search -c conda-forge pcraster

Afterwards you can create a new environment and install PCRaster, e.g. with:

conda create --name pcraster37 python=3.7 -c conda-forge

conda activate pcraster37

conda install -c conda-forge pcraster

You can also combine these steps and install additional packages in one go e.g. by:

conda create --name pcraster37 -c conda-forge python=3.7 pcraster spyder matplotlib

Always use the conda-forge channel when installing further packages into your PCRaster environment.

Note

If you installed previous versions of PCRaster you need to remove their entries from the PATH and PYTHONPATH environment variables before activating your environment. Modifying PATH and PYTHONPATH environment variables as required for previous PCRaster versions is not necessary anymore, this is done automatically when you activate your environment.

Testing your installation

You can execute a few basic steps to check if PCRaster works properly in your conda environment. In case you have not done yet, activate your PCRaster environment and start Python:

$ conda activate pcraster37
$ python

Then import the PCRaster module and create a raster with 6 rows, 4 columns, cell length 1 and 0, 0 as origin. Fill the entire raster with random values drawn from a uniform distribution and display the result:

import pcraster as pcr

pcr.setclone(6, 4, 1, 0, 0)
pcr.aguila(pcr.uniform(1))

You will see that Aguila is displaying the map:

You can also test the PCRaster command line applications. Exit the Python interpreter and type pcrcalc. The usage information will be shown:

$ pcrcalc
pcrcalc 4.3.0 (linux/x86_64)
 USAGE: pcrcalc [options] "expression"
 or     pcrcalc [options] -f scriptFile
  ( or #!: pcrcalc -F [options]+)
 other flags:
  s #  : set seed (integer > 0) for random generator
         default is based on current time
  b f  : overrule script bindings
  1    : update timeseries files at end of each timestep
  r f  : set run directory
  d f  : debug mode, check MV creation on assignment
          comparing against clone or areamap boolean mask
  c    : strict Case significant filename check (Unix portability)
  p    : print profile information
  m    : optimize with areamap MV compression
  l    : use less memory but more temporary disk storage
  t    : test argument substitution

Compiling from source

Note

The following build instructions apply to PCRaster version 4.3 (or later). You don’t want to build earlier versions yourself. Really, you don’t.

Requirements

Building PCRaster depends on various software tools, development packages and libraries, at least:

• Compiler supporting C11 and C++17 (gcc 7 or higher)
• CMake >=3.14
• git
• Python > 3.5
• Boost > 1.66
• NumPy
• GDAL >= 2.0
• Qt > 5.7
• XercesC 3.2

You will need to build libraries yourself in case they are not available on your system or those versions are too old.

Obtaining the sources

Preferably you should use a versioned software release to build PCRaster. This is recommended in case you want to use PCRaster in production. You can obtain a source package as follows:

$ # sha256: 2772ae0dc228cebaf1891623526a097799ab7fe212c606f6d2fe6c3c47b70be6
$ wget http://pcraster.geo.uu.nl/pcraster/packages/src/pcraster-4.3.0.tar.bz2

It is also possible to obtain the PCRaster sources from our code repository, e.g. in case you want to test the latest developments:

$ mkdir pcraster_build
$ cd pcraster_build
$ git clone --recursive https://github.com/pcraster/pcraster.git

Configuring and building

CMake requires an out of source build. Make sure that you check and adapt the install location and Python version:

$ mkdir build
$ cd build

$ cmake -G"Unix Makefiles" ../pcraster -DCMAKE_INSTALL_PREFIX=$HOME/pcraster-4.3.0 -DPython3_EXECUTABLE:FILEPATH=/usr/bin/python3.7

In case some of the 3rd party libraries are not installed in default locations, you need to provide hints before you call CMake. For example, on CentOS 7 you may need to use:

$ export BOOST_INCLUDEDIR=/usr/include/boost169/
$ export BOOST_LIBRARYDIR=/usr/lib64/boost169/
$ export GDAL_ROOT=/tmp/gdal-2.4.1
$ export Qt5_DIR=/tmp/qt5.12.4

# CMake command as above
$ cmake -G"Unix Makefiles" ....

Before you build check the CMake output to ensure that correct library versions are used.

After a successful configure run, build and install PCRaster:

$ NR_CPUS=4
$ cmake --build . --target all -- -j$NR_CPUS
$ cmake --build . --target install

Post-install

After a successful build you will need to add $HOME/pcraster-4.3.0/bin to your PATH environment variable and $HOME/pcraster-4.3.0/python to your PYTHONPATH environment variable to run the PCRaster applications.

Build options

Some build options can be changed. In the build directory type:

$ ccmake .

Toggle and browse to the PCRASTER entries. Modify entries with great care.