apbase.variogram

Shared high-level variogram API.

class apbase.variogram.Variogram(*, n_lags=50, max_pairs=100000, max_distance=0.0)

Bases: object

Fit, select, and evaluate a native variogram model.

Fits candidate semivariogram models from finite source samples and selects the best native model for evaluation or kriging. Coordinates are not projected internally; pass coordinates in the same unit expected by downstream distances.

Parameters:

  • n_lags (int) – Number of lag bins used by the native fitter.

  • max_pairs (int) – Maximum sampled point pairs. 0 uses every eligible pair, capped internally at 1_000_000. An explicit value is capped at apbase.config["variogram_max_pairs_ceiling"] (default 200_000).

  • max_distance (float) – Maximum pair distance considered by the fitter. 0 uses the native default extent.

Examples

>>> import numpy as np
>>> from apbase.variogram import Variogram
>>> x = np.ascontiguousarray([0.0, 10.0, 0.0, 10.0])
>>> y = np.ascontiguousarray([0.0, 0.0, 10.0, 10.0])
>>> z = np.ascontiguousarray([5.0, 7.0, 8.0, 10.0])
>>> variogram = Variogram(n_lags=4, max_pairs=0).fit(x, y, z)
>>> gamma = variogram.evaluate(np.ascontiguousarray([5.0, 10.0]))
property n_lags: int

Number of lag bins used by the native fitter.

Returns:

Lag bin count.

Return type:

int

property max_pairs: int

Maximum sampled point pairs.

Returns:

Pair sampling cap; 0 means every eligible pair subject to the native ceiling.

Return type:

int

property max_distance: float

Maximum pair distance considered by the fitter.

Returns:

Distance cutoff in coordinate units; 0.0 uses the native default extent.

Return type:

float

property n_threads: int

Explicit OpenMP thread count used when evaluating the model.

Resolved live from apbase.config["n_threads"] (see the class docstring) on every access – not cached at construction time.

Returns:

Current OpenMP thread count.

Return type:

int

classmethod from_data(x, y, z, **kwargs)

Create and fit a variogram from source data.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • **kwargs – Keyword arguments forwarded to Variogram.

Returns:

Fitted variogram.

Return type:

Variogram

classmethod from_model(model_values)

Create a variogram from an existing native model vector.

Parameters:

model_values (array_like) – Native model vector with five values: [model_id, nugget, partial_sill, range, sse].

Returns:

Variogram instance backed by model_values.

Return type:

Variogram

property is_fitted: bool

Whether a model is already available.

Returns:

True after fit() or set_model() succeeds.

Return type:

bool

property model_values: ndarray

Native model vector used by kriging and evaluation kernels.

Returns:

Model vector [model_id, nugget, partial_sill, range, sse].

Return type:

numpy.ndarray

property model_params: dict[str, float | int | str]

Readable parameters for the selected variogram model.

Returns:

Model id/name, nugget, partial sill, sill, range, and SSE.

Return type:

dict

property range: float

Selected model range.

Returns:

Fitted variogram range in coordinate units.

Return type:

float

fit(x, y, z)

Fit candidate variogram models from source samples.

Parameters:

  • x (ArrayLike) – One-dimensional source x coordinates.

  • y (ArrayLike) – One-dimensional source y coordinates. Must have the same length as x.

  • z (ArrayLike) – One-dimensional source values. Must have the same length as x and y.

Returns:

The fitted variogram. Rows where x, y, or z are NaN or infinite are ignored.

Return type:

Variogram

Raises:

  • ValueError – If input arrays have inconsistent size or no finite rows.

  • NativeExecutionError – If the native variogram fit reports a failure status.

Examples

>>> variogram = Variogram(n_lags=8, max_pairs=0).fit(x, y, z)
>>> variogram.model_params["model_name"]
'spherical'
set_model(model_values)

Attach an existing native model vector and select its parameters.

Parameters:

model_values (array_like) – Native model vector with five values: [model_id, nugget, partial_sill, range, sse].

Returns:

This instance, marked as fitted.

Return type:

Variogram

Raises:

ValueError – If the model vector shape or contents are invalid.

evaluate(distance)

Evaluate semivariance for distances.

Parameters:

distance (ArrayLike) – Scalar-like or array-like distances in the same coordinate unit used during fit().

Returns:

Semivariance values with the same shape as distance.

Return type:

numpy.ndarray

Examples

>>> gamma = variogram.evaluate(np.asarray([5.0, 10.0]))
apbase.variogram.search_radius(model_params, n_points)

Default local search radius for n_points source points.

range when there are fewer than FULL_RANGE_RADIUS_MAX_POINTS points, range / 3 otherwise.

Parameters:

  • model_params (dict[str, float | int | str])

  • n_points (int)

Return type:

float