Gridpp API

The gridpp library contains functions for the core algorithms in gridpp. Gridpp is written in C++, but automatic wrappers for python and R are created using SWIG. This wiki focuses on examples using the python interface. See the sections on Gridpp in C++ and Gridpp-in-R in the sidebar for specialized info for those languages.

The documentation for all available functions in the API is found at https://metno.github.io/gridpp/. This wiki describes the features of the latest released version of gridpp, however the API reference contains lists of functions for all versions of the API.

After installing the package, gridpp can be loaded with import gridpp. There are no submodules in gridpp, so all functions are accessed with gridpp.<function>. All functions available in the C++ library are also made available in python, with the same function signature. For example, the C++ function:

vec2 neighbourhood (const vec2 &input, int radius, Statistic statistic)

can be used in python as follows:

>>> import gridpp
>>> import numpy as np
>>> gridpp.neighbourhood(np.array([[1,2,3],[4,5,6],[7,8,9]]), 1, gridpp.Mean)
array([[3. , 3.5, 4. ],
       [4.5, 5. , 5.5],
       [6. , 6.5, 7. ]], dtype=float32)

Input data types

The SWIG interface does type checking and casting when required, and the following types can be used:

C++ type	Python types
float	Any scalar
int	Any scalar
vec	1D np.array, list, tuple
vec2	2D np.array, list of lists, tuple of tuples
vec3	3D np.array, list of list of lists, tuple of tuple of tuples
ivec	1D np.array, list, tuple
Statistic	One of gridpp.Min, gridpp.Mean, gridpp.Median, gridpp.Max, gridpp.Std, gridpp.Variance, gridpp.Sum
Extrapolaton	One of gridpp.OneToOne, gridpp.MeanSlope, gridpp.NearestSlope, gridpp.Zero
CoordinateType	One of gridpp.Geodetic, gridpp.Cartesian

For best performance, use numpy arrays since these already store their data sequentially in C. Using tuples or lists incurr a conversion penality. All python vectors are automatically converted to C++ floats when passed to C++ functions that expect floats. Python vectors are automatically converted to C++ ints when passed to C++ functions that expect ints. This means you can pass numpy arrays of any numeric dtype, such as float32, float64, int32. For best performance, however, use numpy arrays with dtypes of float32 and int32, since then no conversion from (for example) double is made.

Output data types

When arrays are returned from the C++ function back to python, they are converted to numpy arrays either of dtype float32 or int32 depending on the output type on the C++ side.

Running on multiple cores

Many gridpp functions are configured to run on multiple processors. To enable this, either set the OMP_NUM_THREADS= environment variable to the number of parallel threads to use, or call the following function, before calling any other functions:

gridpp.set_omp_threads(4)

If OMP_NUM_THREADS= is not set and gridpp.set_omp_threads() is never called, a default of 1 thread will be used. This applies not only to python, but C++, and R bindings.

Exceptions

Functions will throw std::invalid_argument exceptions when input arguments are invalid and std::runtime_error for other errors. These exceptions are passed through the SWIG layer and trapped by the language bindings. The language bindings can in addition throw a type error exception when the wrong object type is passed to the function. Here is how the exceptions are translated into python:

C++	Python	Causes
std::invalid_argument	ValueError	Invalid argument value (for example a negative radius, or dimension mismatch among arguments)
N/A	TypeError	Argument has wrong type (for example passing an array when a scalar is expected)
std::runtime_error	RuntimeError	Error during processing