geopytorch 0.1.0__tar.gz

geopytorch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Tinoco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geopytorch-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: geopytorch
+Version: 0.1.0
+Summary: Kriging built on GPyTorch
+Author: Daniel Tinoco
+Author-email: Daniel Tinoco <dbtnc.ps2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: gpytorch>=1.15.2
+Requires-Dist: numpy>=1.26,<2 ; platform_machine == 'x86_64' and sys_platform == 'darwin'
+Requires-Dist: numpy>=2 ; platform_machine != 'x86_64' or sys_platform != 'darwin'
+Requires-Dist: torch>=2.2,<2.3 ; platform_machine == 'x86_64' and sys_platform == 'darwin'
+Requires-Dist: torch>=2.4 ; platform_machine != 'x86_64' or sys_platform != 'darwin'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/dbtnc/geopytorch
+Project-URL: Issues, https://github.com/dbtnc/geopytorch/issues
+Description-Content-Type: text/markdown
+
+# GeoPyTorch
+
+## R package
+
+The R interface is in `r-package/geopytorch-r`. See its
+[README](https://github.com/dbtnc/geopytorch/blob/main/r-package/geopytorch-r/README.md)
+for how to use it from R.
+
+## Quick start
+
+```python
+import torch
+
+from geopytorch import OrdinaryKriging, SimpleKriging
+
+train_x = torch.tensor([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
+train_y = torch.tensor([1.2, 2.0, 0.7, 1.8])
+target_x = torch.tensor([[0.25, 0.40], [0.75, 0.60]])
+
+simple = SimpleKriging(mean=1.4, ard=True).fit(train_x, train_y)
+simple_prediction = simple.predict(target_x)
+
+ordinary = OrdinaryKriging(ard=True).fit(train_x, train_y)
+ordinary_prediction = ordinary.predict(target_x)
+
+print(ordinary_prediction.mean)
+print(ordinary_prediction.standard_deviation)
+```
+
+Choose a covariance model with `covariance_model`:
+
+```python
+ordinary = OrdinaryKriging(covariance_model="spherical").fit(train_x, train_y)
+```
+
+Supported models are `"gaussian"`, `"exponential"`, `"matern"`,
+`"spherical"`, and `"wave"`.
+
+## Covariance kernels
+
+The built-in kernels use the geostatistical range parameter `phi` directly:
+
+| Model | Correlation at distance `h` |
+|---|---|
+| Gaussian | `exp(-(h / phi) ** 2)` |
+| Exponential | `exp(-h / phi)` |
+| Matérn | Matérn with Bessel argument `h / phi` |
+| Spherical | `1 - 1.5 h/phi + 0.5 (h/phi) ** 3` for `h < phi`; zero otherwise |
+| Wave | `(phi / h) sin(h / phi)`, with value one at `h = 0` |
+
+For Matérn, `matern_nu` is the smoothness parameter; the supported values are
+`0.5`, `1.5`, and `2.5`. Spherical and wave kernels are restricted to at most
+three spatial dimensions, covering the current 2D and planned 3D use cases.
+
+`predict()` returns a `KrigingPrediction` containing the joint covariance as
+well as marginal variance and standard deviation. It predicts the latent
+spatial signal by default. Use `observation_noise=True` to include the fitted
+nugget in a future noisy observation:
+
+```python
+observed_prediction = ordinary.predict(target_x, observation_noise=True)
+lower, upper = observed_prediction.confidence_region()
+```
+
+## Covariance parameter estimation
+
+`OrdinaryKriging` supports both maximum likelihood and restricted maximum
+likelihood. REML profiles the unknown constant mean out of a dense Gaussian
+restricted-likelihood objective. L-BFGS is available for deterministic
+likelihood optimization:
+
+```python
+ordinary = OrdinaryKriging(covariance_model="exponential").fit(
+    train_x,
+    train_y,
+    likelihood_method="reml",
+    optimizer="lbfgs",
+    training_iterations=50,
+    learning_rate=1.0,
+)
+print(ordinary.restricted_log_likelihood_)
+```
+
+REML is not exposed for `SimpleKriging`: its constant mean is known rather
+than an unknown fixed effect. Use the default maximum-likelihood objective to
+estimate its covariance parameters.
+
+## Known covariance parameters
+
+Both estimators default to a scaled Matérn-3/2 kernel and a
+homoskedastic Gaussian likelihood. To perform classical Kriging with parameters
+supplied by the user, construct a covariance kernel and skip likelihood
+optimization:
+
+```python
+import gpytorch
+from geopytorch import covariance_kernel
+
+kernel = covariance_kernel("matern", matern_nu=1.5, ard_num_dims=2)
+kernel.initialize(outputscale=2.0)
+kernel.base_kernel.initialize(lengthscale=torch.tensor([0.4, 0.8]))
+
+likelihood = gpytorch.likelihoods.GaussianLikelihood()
+likelihood.initialize(noise=0.05)
+
+ordinary = OrdinaryKriging(kernel=kernel, likelihood=likelihood)
+ordinary.fit(train_x, train_y, training_iterations=0)
+```
+
+Simple Kriging freezes its known constant mean. Ordinary Kriging uses a
+trainable constant while fitting covariance hyperparameters, then applies the
+exact unit-sum weight and mean-uncertainty corrections during prediction.

geopytorch-0.1.0/README.md

@@ -0,0 +1,112 @@
+# GeoPyTorch
+
+## R package
+
+The R interface is in `r-package/geopytorch-r`. See its
+[README](https://github.com/dbtnc/geopytorch/blob/main/r-package/geopytorch-r/README.md)
+for how to use it from R.
+
+## Quick start
+
+```python
+import torch
+
+from geopytorch import OrdinaryKriging, SimpleKriging
+
+train_x = torch.tensor([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
+train_y = torch.tensor([1.2, 2.0, 0.7, 1.8])
+target_x = torch.tensor([[0.25, 0.40], [0.75, 0.60]])
+
+simple = SimpleKriging(mean=1.4, ard=True).fit(train_x, train_y)
+simple_prediction = simple.predict(target_x)
+
+ordinary = OrdinaryKriging(ard=True).fit(train_x, train_y)
+ordinary_prediction = ordinary.predict(target_x)
+
+print(ordinary_prediction.mean)
+print(ordinary_prediction.standard_deviation)
+```
+
+Choose a covariance model with `covariance_model`:
+
+```python
+ordinary = OrdinaryKriging(covariance_model="spherical").fit(train_x, train_y)
+```
+
+Supported models are `"gaussian"`, `"exponential"`, `"matern"`,
+`"spherical"`, and `"wave"`.
+
+## Covariance kernels
+
+The built-in kernels use the geostatistical range parameter `phi` directly:
+
+| Model | Correlation at distance `h` |
+|---|---|
+| Gaussian | `exp(-(h / phi) ** 2)` |
+| Exponential | `exp(-h / phi)` |
+| Matérn | Matérn with Bessel argument `h / phi` |
+| Spherical | `1 - 1.5 h/phi + 0.5 (h/phi) ** 3` for `h < phi`; zero otherwise |
+| Wave | `(phi / h) sin(h / phi)`, with value one at `h = 0` |
+
+For Matérn, `matern_nu` is the smoothness parameter; the supported values are
+`0.5`, `1.5`, and `2.5`. Spherical and wave kernels are restricted to at most
+three spatial dimensions, covering the current 2D and planned 3D use cases.
+
+`predict()` returns a `KrigingPrediction` containing the joint covariance as
+well as marginal variance and standard deviation. It predicts the latent
+spatial signal by default. Use `observation_noise=True` to include the fitted
+nugget in a future noisy observation:
+
+```python
+observed_prediction = ordinary.predict(target_x, observation_noise=True)
+lower, upper = observed_prediction.confidence_region()
+```
+
+## Covariance parameter estimation
+
+`OrdinaryKriging` supports both maximum likelihood and restricted maximum
+likelihood. REML profiles the unknown constant mean out of a dense Gaussian
+restricted-likelihood objective. L-BFGS is available for deterministic
+likelihood optimization:
+
+```python
+ordinary = OrdinaryKriging(covariance_model="exponential").fit(
+    train_x,
+    train_y,
+    likelihood_method="reml",
+    optimizer="lbfgs",
+    training_iterations=50,
+    learning_rate=1.0,
+)
+print(ordinary.restricted_log_likelihood_)
+```
+
+REML is not exposed for `SimpleKriging`: its constant mean is known rather
+than an unknown fixed effect. Use the default maximum-likelihood objective to
+estimate its covariance parameters.
+
+## Known covariance parameters
+
+Both estimators default to a scaled Matérn-3/2 kernel and a
+homoskedastic Gaussian likelihood. To perform classical Kriging with parameters
+supplied by the user, construct a covariance kernel and skip likelihood
+optimization:
+
+```python
+import gpytorch
+from geopytorch import covariance_kernel
+
+kernel = covariance_kernel("matern", matern_nu=1.5, ard_num_dims=2)
+kernel.initialize(outputscale=2.0)
+kernel.base_kernel.initialize(lengthscale=torch.tensor([0.4, 0.8]))
+
+likelihood = gpytorch.likelihoods.GaussianLikelihood()
+likelihood.initialize(noise=0.05)
+
+ordinary = OrdinaryKriging(kernel=kernel, likelihood=likelihood)
+ordinary.fit(train_x, train_y, training_iterations=0)
+```
+
+Simple Kriging freezes its known constant mean. Ordinary Kriging uses a
+trainable constant while fitting covariance hyperparameters, then applies the
+exact unit-sum weight and mean-uncertainty corrections during prediction.

geopytorch-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "geopytorch"
+version = "0.1.0"
+description = "Kriging built on GPyTorch"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "gpytorch>=1.15.2",
+    "numpy>=1.26,<2; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "numpy>=2; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+    "torch>=2.2,<2.3; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "torch>=2.4; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+]
+
+[[project.authors]]
+name = "Daniel Tinoco"
+email = "dbtnc.ps2@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/dbtnc/geopytorch"
+Issues = "https://github.com/dbtnc/geopytorch/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "air-formatter>=0.12.0",
+    "prek>=0.5.5",
+    "pytest>=9.1.1",
+    "ruff>=0.17.0",
+]

geopytorch-0.1.0/pyproject.toml.orig

@@ -0,0 +1,33 @@
+[project]
+name = "geopytorch"
+version = "0.1.0"
+description = "Kriging built on GPyTorch"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Daniel Tinoco", email = "dbtnc.ps2@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "gpytorch>=1.15.2",
+    "numpy>=1.26,<2; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "numpy>=2; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+    "torch>=2.2,<2.3; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "torch>=2.4; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "air-formatter>=0.12.0",
+    "prek>=0.5.5",
+    "pytest>=9.1.1",
+    "ruff>=0.17.0",
+]
+[project.urls]
+Homepage = "https://github.com/dbtnc/geopytorch"
+Issues = "https://github.com/dbtnc/geopytorch/issues"

geopytorch-0.1.0/src/geopytorch/__init__.py

@@ -0,0 +1,29 @@
+"""GeoPyTorch public API."""
+
+from geopytorch.covariance import (
+    COVARIANCE_MODELS,
+    CovarianceModel,
+    ExponentialKernel,
+    GaussianKernel,
+    MaternKernel,
+    SphericalKernel,
+    WaveKernel,
+    covariance_kernel,
+)
+from geopytorch.kriging import KrigingPrediction, OrdinaryKriging, SimpleKriging
+from geopytorch.regression import SpatialLinearModel
+
+__all__ = [
+    "COVARIANCE_MODELS",
+    "CovarianceModel",
+    "ExponentialKernel",
+    "GaussianKernel",
+    "KrigingPrediction",
+    "MaternKernel",
+    "OrdinaryKriging",
+    "SimpleKriging",
+    "SpatialLinearModel",
+    "SphericalKernel",
+    "WaveKernel",
+    "covariance_kernel",
+]

geopytorch-0.1.0/src/geopytorch/covariance.py

@@ -0,0 +1,179 @@
+# Expected inputs: Coordinate tensors and positive range parameters.
+# Expected outputs: GPyTorch kernels for supported stationary covariance models.
+
+"""Covariance kernels built on GPyTorch."""
+
+from __future__ import annotations
+
+from math import pi
+from typing import Literal
+
+import gpytorch
+import torch
+from torch import Tensor
+
+type CovarianceModel = Literal[
+    "gaussian", "exponential", "matern", "spherical", "wave"
+]
+COVARIANCE_MODELS: tuple[CovarianceModel, ...] = (
+    "gaussian",
+    "exponential",
+    "matern",
+    "spherical",
+    "wave",
+)
+
+
+class DistanceKernel(gpytorch.kernels.Kernel):
+    r"""Base for stationary kernels expressed through scaled distance.
+
+    ``has_lengthscale`` asks GPyTorch to provide a positive trainable range,
+    including batching and optional per-coordinate ARD parameters.  It does
+    not, by itself, define how that parameter enters a covariance formula.
+    This class supplies one convention shared by all subclasses:
+
+    .. math::
+        r = \left\lVert \mathbf{x}_1/\boldsymbol{\phi}
+            - \mathbf{x}_2/\boldsymbol{\phi}\right\rVert_2.
+
+    Each subclass therefore receives the same dimensionless distance ``r``
+    and states its correlation directly in terms of ``r``.  Centralizing this
+    step prevents hidden, model-specific distance factors from changing the
+    geostatistical meaning of the public range parameter ``phi`` (stored by
+    GPyTorch under its standard ``lengthscale`` property).
+    """
+
+    has_lengthscale = True
+
+    def _scaled_distance(
+        self, x1: Tensor, x2: Tensor, *, diag: bool, **params: object
+    ) -> Tensor:
+        return self.covar_dist(
+            x1.div(self.lengthscale),
+            x2.div(self.lengthscale),
+            diag=diag,
+            **params,
+        )
+
+
+class GaussianKernel(DistanceKernel):
+    r"""Gaussian correlation :math:`\exp[-(h/\phi)^2]`."""
+
+    def forward(
+        self, x1: Tensor, x2: Tensor, diag: bool = False, **params: object
+    ) -> Tensor:
+        distance = self._scaled_distance(x1, x2, diag=diag, **params)
+        return torch.exp(-distance.square())
+
+
+class ExponentialKernel(DistanceKernel):
+    r"""Exponential correlation :math:`\exp(-h/\phi)`."""
+
+    def forward(
+        self, x1: Tensor, x2: Tensor, diag: bool = False, **params: object
+    ) -> Tensor:
+        distance = self._scaled_distance(x1, x2, diag=diag, **params)
+        return torch.exp(-distance)
+
+
+class MaternKernel(DistanceKernel):
+    r"""Matérn correlation with Bessel argument :math:`h/\phi`.
+
+    The supported smoothness values match GPyTorch's exact Matérn kernel:
+    ``0.5``, ``1.5``, and ``2.5``. Unlike GPyTorch's native parameterization,
+    ``lengthscale`` here is the geostatistical range ``phi`` without a
+    :math:`\sqrt{2\nu}` factor.
+    """
+
+    def __init__(self, nu: float = 1.5, **kwargs: object) -> None:
+        if nu not in (0.5, 1.5, 2.5):
+            raise ValueError("nu must be one of 0.5, 1.5, or 2.5")
+        super().__init__(**kwargs)
+        self.nu = float(nu)
+
+    def forward(
+        self, x1: Tensor, x2: Tensor, diag: bool = False, **params: object
+    ) -> Tensor:
+        distance = self._scaled_distance(x1, x2, diag=diag, **params)
+        exponential = torch.exp(-distance)
+        if self.nu == 0.5:
+            polynomial: Tensor | float = 1.0
+        elif self.nu == 1.5:
+            polynomial = 1.0 + distance
+        else:
+            polynomial = 1.0 + distance + distance.square() / 3.0
+        return polynomial * exponential
+
+
+class SphericalKernel(DistanceKernel):
+    r"""Spherical correlation with compact-support range ``phi``."""
+
+    def forward(
+        self, x1: Tensor, x2: Tensor, diag: bool = False, **params: object
+    ) -> Tensor:
+        _require_at_most_three_dimensions(x1, "SphericalKernel")
+        distance = self._scaled_distance(x1, x2, diag=diag, **params)
+        within_range = 1.0 - 1.5 * distance + 0.5 * distance.pow(3)
+        return torch.where(
+            distance < 1.0, within_range, torch.zeros_like(distance)
+        )
+
+
+class WaveKernel(DistanceKernel):
+    r"""Wave correlation :math:`(\phi/h)\sin(h/\phi)`."""
+
+    def forward(
+        self, x1: Tensor, x2: Tensor, diag: bool = False, **params: object
+    ) -> Tensor:
+        _require_at_most_three_dimensions(x1, "WaveKernel")
+        distance = self._scaled_distance(x1, x2, diag=diag, **params)
+        return torch.sinc(distance / pi)
+
+
+def covariance_kernel(
+    covariance_model: CovarianceModel = "matern",
+    *,
+    matern_nu: float = 1.5,
+    ard_num_dims: int | None = None,
+) -> gpytorch.kernels.ScaleKernel:
+    """Return a scaled kernel using partial sill ``sigma^2`` and range ``phi``.
+
+    The returned ``ScaleKernel.outputscale`` is the partial sill ``sigma^2``.
+    Its base kernel's ``lengthscale`` is the range ``phi`` used directly in
+    the selected geostatistical correlation formula.
+    """
+
+    if covariance_model not in COVARIANCE_MODELS:
+        choices = ", ".join(COVARIANCE_MODELS)
+        raise ValueError(f"covariance_model must be one of: {choices}")
+    kernel_options = {"ard_num_dims": ard_num_dims}
+    if covariance_model == "gaussian":
+        base_kernel = GaussianKernel(**kernel_options)
+    elif covariance_model == "exponential":
+        base_kernel = ExponentialKernel(**kernel_options)
+    elif covariance_model == "matern":
+        base_kernel = MaternKernel(nu=matern_nu, **kernel_options)
+    elif covariance_model == "spherical":
+        base_kernel = SphericalKernel(**kernel_options)
+    else:
+        base_kernel = WaveKernel(**kernel_options)
+    return gpytorch.kernels.ScaleKernel(base_kernel)
+
+
+def _require_at_most_three_dimensions(x: Tensor, kernel_name: str) -> None:
+    if x.shape[-1] > 3:
+        raise ValueError(
+            f"{kernel_name} is positive definite only for up to 3 spatial dimensions"
+        )
+
+
+__all__ = [
+    "COVARIANCE_MODELS",
+    "CovarianceModel",
+    "ExponentialKernel",
+    "GaussianKernel",
+    "MaternKernel",
+    "SphericalKernel",
+    "WaveKernel",
+    "covariance_kernel",
+]