The PCRaster Python multicore module

New in version 4.2.

Introduction

In case your installation of PCRaster contains the pcraster.multicore submodule (default on Windows), then you can use it to speed up certain operations. This module contains alternative implementations of a subset of the PCRaster operations that are capable of distributing their workload across more than one CPU core. Check module description of the pcraster.multicore module for a list of supported operations (mostly local and focal operations).

Usage

To use these operations, all you have to do is set the environment variable PCRASTER_NR_WORKER_THREADS to the number of threads PCRaster should use. In case your machine has not much else to do you can set it to the number of CPU cores available. Otherwise, choose a smaller value.

To use, for example, 4 worker threads on Windows use

set PCRASTER_NR_WORKER_THREADS=4

and on Unices use

export PCRASTER_NR_WORKER_THREADS=4

Changes to your model script are not required, the multicore module will check whether the provided arguments of operations are supported by the multicore module. If not, the module will fall back to the classic PCRaster implementation.

In case of focal operations, like windowaverage and windowtotal, you must provide a window length that corresponds to an odd number of cells. The underlying multicore implementation is faster than the classic PCRaster implementation, but does not support handling fractions of cells, which the original algorithm does. So, when the window size is not an odd integral value, the classic implementation will be used.

Reference documentation

Module description

This is the PCRaster multicore package.

PCRaster is a collection of tools and software libraries tailored to the construction of spatio-temporal models. Information about the development of PCRaster and its application in environmental modelling can be found at http://www.pcraster.eu

The multicore module provides alternative, multi-threaded implementations of several PCRaster operations. The following operators and operations are able to exploit multiple processors:

+ - * /
< <= > >= == !=
**
& | ! ^
defined, cover
ifthen, ifthenelse
max, min
boolean, nominal, ordinal, scalar
sqr, sqrt, abs, fac, ln, log10
rounddown, roundup, roundoff
cos, sin, tan, acos, asin, atan
slope, window4total, windowtotal, windowaverage
mapmaximum, mapminimum

To set or query the number of worker threads use:

set_nr_worker_threads, nr_worker_threads

List of operations

pcraster.multicore._operations.abs(arg1)

Cell-wise absolute value of an expression.

pcraster.multicore._operations.acos(arg1)

Cell-wise inverse cosine.

pcraster.multicore._operations.add(arg1, arg2)

Add arguments cell-wise. Equivalent to ‘expression1 + expression2’.

pcraster.multicore._operations.asin(arg1)

Cell-wise inverse sine.

pcraster.multicore._operations.atan(arg1)

Cell-wise inverse tangent.

pcraster.multicore._operations.boolean(arg1)

Cell-wise conversion of expression to boolean data type.

pcraster.multicore._operations.cos(arg1)

Cell-wise cosine.

pcraster.multicore._operations.cover(*args)

Cell-wise, substitutes missing values with values taken from one or more expressions

pcraster.multicore._operations.defined(arg1)

Cell-wise, returns whether the cell value on expression is a missing value or not.

pcraster.multicore._operations.div(arg1, arg2)

Divide arguments cell-wise. Equivalent to ‘expression1 / expression2’.

pcraster.multicore._operations.equal(arg1, arg2)

Cell-wise relational equal-to operation. Equivalent to ‘expression1 == expression2’.

pcraster.multicore._operations.fac(arg1)

Cell-wise factorial of a natural positive number of an expression.

pcraster.multicore._operations.greater(arg1, arg2)

Cell-wise relational greater-than operation. Equivalent to ‘expression1 < expression2’.

pcraster.multicore._operations.greater_equal(arg1, arg2)

Cell-wise relational greater-than-or-equal-to operation. Equivalent to ‘expression1 >= expression2’.

pcraster.multicore._operations.ifthen(arg1, arg2)

Cell-wise, for True values on condition expression1 is assigned, missing value otherwise.

pcraster.multicore._operations.ifthenelse(arg1, arg2, arg3)

Cell-wise, for True values on condition expression1 is assigned, expression2 otherwise.

pcraster.multicore._operations.less(arg1, arg2)

Cell-wise relational less-than operation. Equivalent to ‘expression1 < expression2’.

pcraster.multicore._operations.less_equal(arg1, arg2)

Cell-wise relational less-than-or-equal-to operation. Equivalent to ‘expression1 <= expression2’.

pcraster.multicore._operations.ln(arg1)

Cell-wise natural logarithm of an expression.

pcraster.multicore._operations.log10(arg1)

Cell-wise base 10 logarithm of an expression.

pcraster.multicore._operations.mapmaximum(arg1)

Maximum cell value of the expression.

pcraster.multicore._operations.mapminimum(arg1)

Minimum cell value of the expression.

pcraster.multicore._operations.max(*args)

Cell-wise maximum value of multiple expressions.

pcraster.multicore._operations.min(*args)

Cell-wise minimum value of multiple expressions.

pcraster.multicore._operations.mul(arg1, arg2)

Multiply arguments cell-wise. Equivalent to ‘expression1 * expression2’.

pcraster.multicore._operations.nominal(arg1)

Cell-wise conversion of expression to nominal data type.

pcraster.multicore._operations.nr_worker_threads()

Returns the number of worker threads currently used in the PCRaster multicore algorithms

pcraster.multicore._operations.ordinal(arg1)

Cell-wise conversion of expression to ordinal data type.

pcraster.multicore._operations.power(arg1, arg2)

Cell-wise base raised to the power exponent. Equivalent to ‘base ** exponent’.

pcraster.multicore._operations.rounddown(arg1)

Cell-wise the value of an expression is rounded downwards.

pcraster.multicore._operations.roundoff(arg1)

Cell-wise the value of an expression is rounded off.

pcraster.multicore._operations.roundup(arg1)

Cell-wise the value of an expression is rounded upwards.

pcraster.multicore._operations.scalar(arg1)

Cell-wise conversion of expression to scalar data type.

pcraster.multicore._operations.set_nr_worker_threads(arg1)

Set the number of worker threads to be used in the PCRaster multicore algorithms

pcraster.multicore._operations.sin(arg1)

Cell-wise sine.

pcraster.multicore._operations.slope(arg1)

Cell-wise slope on basis of the elevation ‘dem’.

pcraster.multicore._operations.sqr(arg1)

Cell-wise square of an expression.

pcraster.multicore._operations.sqrt(arg1)

Cell-wise square root of an expression.

pcraster.multicore._operations.sub(arg1, arg2)

Subtract arguments cell-wise. Equivalent to ‘expression1 - expression2’.

pcraster.multicore._operations.tan(arg1)

Cell-wise tangent.

pcraster.multicore._operations.unequal(arg1, arg2)

Cell-wise relational not-equal-to operation. Equivalent to ‘expression1 != expression2’.

pcraster.multicore._operations.window4total(arg1)

Cell-wise, sums the values of the four cells which lie above, below, left and right of the cell.

pcraster.multicore._operations.windowaverage(arg1, arg2)

Cell-wise, averages the values of a square window defined by windowlength.

pcraster.multicore._operations.windowtotal(arg1, arg2)

Cell-wise, sums the values of a square window defined by windowlength.

Indices and tables