pykriging.kriging#

Python wrapper for the Fortran kriging module via ISO C Binding.

Build the shared library first:
gfortran -O2 -fPIC -fdefault-real-8 -fopenmp -shared

common.f90 utils.F90 rotation.f90 variogram.f90 kriging.F90 kriging_capi.f90 -o libkriging.so

Then use this module:

from pykriging import Kriging import numpy as np

# Spatial ordinary kriging k = Kriging(ndim=2, nvar=1) k.set_obs(ivar=1, coord=coord, value=value, nmax=20) k.set_grid(coord=grid_coord) k.set_vgm(ivar=1, jvar=1, vtype=”sph”, nugget=0, sill=1.0, a_major=1000, a_minor1=500, a_minor2=500) k.set_search(ivar=1) k.solve() est, var = k.get_results() del k # release memory

# Space-time kriging — same entry point, st=True k = Kriging(st=True, nvar=1) k.set_st_model(model=’sum_metric’, transform=’bounded’, at=5.0) …

Kriging is a factory function that returns either a _SpatialKriging or SpaceTimeKriging instance depending on the st keyword.

Functions#

omp_info(→ dict)

Return a dict with OpenMP thread counts as seen by the Fortran runtime.

get_omp_info()

Kriging([st])

Create a kriging object — spatial or space-time.

ordinary_kriging(→ tuple[numpy.ndarray, numpy.ndarray])

One-shot ordinary kriging with a single isotropic (or anisotropic) variogram.

cokriging(→ tuple[numpy.ndarray, numpy.ndarray])

One-shot ordinary co-kriging with multiple variables.

sequential_gaussian_simulation(→ numpy.ndarray)

Sequential Gaussian Simulation.

Module Contents#

pykriging.kriging.omp_info() → dict#

Return a dict with OpenMP thread counts as seen by the Fortran runtime.

Keys#

max_threadsint

Value of omp_get_max_threads() — the number of threads that will be used in the next parallel region (respects OMP_NUM_THREADS and any omp_set_num_threads() calls). Returns 1 when OpenMP is not compiled in.

num_threadsint

Value of omp_get_num_threads() measured inside an actual parallel region — the number of threads that are actually running. Returns 1 when OpenMP is not compiled in.

openmpbool

True when the library was compiled with OpenMP support.

Example

>>> import os; os.environ["OMP_NUM_THREADS"] = "4"
>>> from _kriging import omp_info
>>> omp_info()
{'max_threads': 4, 'num_threads': 4, 'openmp': True}
pykriging.kriging.get_omp_info()#
pykriging.kriging.Kriging(st: bool = False, **kwargs)#

Create a kriging object — spatial or space-time.

This is the primary entry point for both backends. Pass st=True to obtain a SpaceTimeKriging instance; omit it (or st=False) for ordinary spatial kriging (_SpatialKriging).

Parameters:

  • st (bool, default False) – False — spatial kriging (_SpatialKriging). True — space-time kriging (SpaceTimeKriging).

  • **kwargs –

    Forwarded verbatim to the chosen constructor.

    Spatial-only parameters (ndim, varying_vgm, std_ck, pf_cache) are silently removed when st=True; a UserWarning is emitted for any that were supplied with a non-default value so they are not silently ignored.

Returns:

  • _SpatialKriging – When st=False. Full set of methods: set_obs(), set_vgm(), set_grid(), set_search(), solve(), get_results(), and more.

  • SpaceTimeKriging – When st=True. Same core methods plus set_st_model(), set_vgm_temporal(), and set_vgm_joint_sills(). set_grid() requires an extra time= argument. set_search() requires extra time_* arguments.

Notes

Factory, not a class: Kriging is a function that returns one of two concrete types. Use isinstance(k, _SpatialKriging) or isinstance(k, SpaceTimeKriging) for type checks.

Output shape: get_results() shapes are consistent within each backend but differ when nsim > 1:

  • spatial — estimate (nblocks, nvar, nsim) squeezed to (nblocks,) for nvar=1, nsim=1.

  • ST — estimate (nsim, nblocks) squeezed to (nblocks,) for nsim=1.

Examples

Spatial ordinary kriging:

k = Kriging(ndim=2, nvar=1)
k.set_obs(ivar=1, coord=coord, value=value, nmax=20)
k.set_grid(coord=grid_coord)
k.set_vgm(ivar=1, jvar=1, vtype="sph", sill=1.0, a_major=500)
k.set_search(ivar=1)
k.solve()
est, var = k.get_results()

Space-time ordinary kriging:

k = Kriging(st=True, nvar=1)
k.set_st_model(model='sum_metric', transform='bounded', at=5.0)
k.set_obs(ivar=1, coord=obs_coord4, value=obs_value, nmax=30)
k.set_vgm(ivar=1, jvar=1, vtype="sph", sill=0.8, a_major=1000)
k.set_vgm_temporal(ivar=1, jvar=1, vtype="exp", sill=0.6, at_k=10.0)
k.set_vgm_joint_sills(1, 1, 0.4)
k.set_grid(coord=grid_coord, time=grid_time)
k.set_search(ivar=1)
k.solve()
est, var = k.get_results()
pykriging.kriging.ordinary_kriging(obs_coord: numpy.ndarray, obs_value: numpy.ndarray, grid_coord: numpy.ndarray, vgm_spec: dict | list[dict], nmax: int | None = None, maxdist: float | None = None, search_anis1: float = 1.0, search_anis2: float = 1.0, search_azimuth: float = 0.0, rangescale: float | None = None, localnugget: float | None = None, nthread=0, ncache: int | None = None) → tuple[numpy.ndarray, numpy.ndarray]#

One-shot ordinary kriging with a single isotropic (or anisotropic) variogram.

Parameters:

  • obs_coord (ndarray, shape (nobs, ndim)) – Observation coordinates. Rows are points, columns are spatial dimensions.

  • obs_value (ndarray, shape (nobs,)) – Observation values.

  • grid_coord (ndarray, shape (ngrid, ndim)) – Grid coordinates to estimate.

  • vgm_spec (dict or list of dict) – One variogram structure dict, or a list of dicts for nested models. Each dict is passed as keyword arguments to Kriging.set_vgm() (keys: vtype, nugget, sill, a_major, and optionally a_minor1, a_minor2, azimuth, dip, plunge).

  • nmax (int) – Maximum number of neighbours.

  • maxdist (float, optional) – Maximum search distance.

  • search_anis1 (float) – Anisotropy ratios for search ellipse (1.0 = isotropic).

  • search_anis2 (float) – Anisotropy ratios for search ellipse (1.0 = isotropic).

  • search_azimuth (float) – Azimuth of search ellipse major axis (degrees from North).

  • nthread (int) – max OMP threads for this call (0 or absent = OMP default)

  • ncache (int, optional) – Per-thread hcache slots for this solve. None uses the default.

Returns:

  • estimate (ndarray, shape (ngrid,))

  • variance (ndarray, shape (ngrid,))

Example

>>> est, var = ordinary_kriging(
...     obs_coord, obs_value, grid_coord,
...     vgm_spec=dict(vtype="sph", nugget=100, sill=900, a_major=1000, a_minor1=500),
...     nmax=20)
pykriging.kriging.cokriging(obs_coords: list[numpy.ndarray], obs_values: list[numpy.ndarray], grid_coord: numpy.ndarray, vgm_spec: dict, nmax: int | None = None, rangescale: float | None = None, localnugget: float | None = None, nthread: int = 0, ncache: int | None = None, std_ck: bool = False) → tuple[numpy.ndarray, numpy.ndarray]#

One-shot ordinary co-kriging with multiple variables.

Parameters:

  • obs_coords (list of ndarray, each shape (nobs_i, ndim)) – Observation coordinates per variable. Rows are points.

  • obs_values (list of ndarray, each shape (nobs_i,)) – Observation values per variable.

  • grid_coord (ndarray, shape (ngrid, ndim)) – Grid coordinates.

  • vgm_spec (dict) – Mapping (ivar, jvar) to a variogram dict or list of dicts. Each dict is passed as keyword arguments to Kriging.set_vgm(). Both (i,j) and (j,i) can be provided; if only (i,j) is given, (j,i) will mirror it automatically (handled inside Fortran set_vgm).

  • nmax (int) – Maximum neighbours per variable.

  • nthread (int) – max OMP threads for this call (0 or absent = OMP default)

  • ncache (int, optional) – Per-thread hcache slots for this solve. None uses the default.

  • std_ck (bool) – Use standard Ordinary Kriging.

Returns:

  • estimate (ndarray, shape (ngrid,))

  • variance (ndarray, shape (ngrid,))

Example

>>> est, var = cokriging(
...     obs_coords=[coord1, coord2],
...     obs_values=[val1, val2],
...     grid_coord=grid,
...     vgm_spec={
...         (1,1): dict(vtype="sph", nugget=100, sill=900, a_major=1000, a_minor1=500),
...         (2,2): dict(vtype="sph", nugget=50,  sill=450, a_major=1000, a_minor1=500),
...         (1,2): dict(vtype="sph", nugget=0,   sill=600, a_major=1000, a_minor1=500),
...     })
pykriging.kriging.sequential_gaussian_simulation(obs_coord: numpy.ndarray, obs_value: numpy.ndarray, grid_coord: numpy.ndarray, vgm_spec: str, nsim: int, nmax: int | None = None, randpath: numpy.ndarray | None = None, sample: numpy.ndarray | None = None, seed: int | None = None, rangescale: float | None = None, localnugget: float | None = None, nthread: int = 0, ncache: int | None = None) → numpy.ndarray#

Sequential Gaussian Simulation.

Parameters:

  • obs_coord (ndarray, shape (nobs, ndim)) – Observation coordinates. Rows are points, columns are spatial dimensions.

  • obs_value (ndarray, shape (nobs,)) – Observation values.

  • grid_coord (ndarray, shape (ngrid, ndim)) – Grid coordinates.

  • vgm_spec (dict or list of dict) – One or more nested variogram structure dicts, each passed as keyword arguments to Kriging.set_vgm().

  • nsim (int) – Number of realisations.

  • nmax (int) – Maximum neighbours (includes previously simulated nodes).

  • seed (int, optional) – Random seed for reproducibility.

  • nthread (int) – max OMP threads for this call (0 or absent = OMP default)

  • ncache (int, optional) – Per-thread hcache slots for this solve. None uses the default.

Returns:

simulations (ndarray, shape (nsim, ngrid)) – Each row is one realisation in the original (non-randomised) block order.