0
# GSTools
1

2
GSTools is a comprehensive geostatistical toolbox for Python that provides advanced spatial analysis and modeling capabilities. It offers functionality for random field generation with periodic boundaries, various kriging methods, conditioned field generation, automated variogram estimation and fitting, directional variogram modeling, data normalization and transformation, numerous built-in and user-defined covariance models, metric spatio-temporal modeling, plurigaussian field simulations, and comprehensive plotting and export routines.
3

4
## Package Information
5

6
- **Package Name**: gstools
7
- **Language**: Python
8
- **Installation**: `pip install gstools`
9
- **Documentation**: https://gstools.readthedocs.io
10
- **Version**: 1.7.0
11
- **License**: LGPL-3.0
12

13
## Core Imports
14

15
```python
16
import gstools as gs
17
```
18

19
Import specific components:
20

21
```python
22
from gstools import Gaussian, SRF, Krige, vario_estimate, PGS
23
```
24

25
## Basic Usage
26

27
```python
28
import gstools as gs
29
import numpy as np
30

31
# Define a covariance model
32
model = gs.Gaussian(dim=2, var=1.0, len_scale=10.0)
33

34
# Generate a random field
35
srf = gs.SRF(model)
36
grid = [np.arange(0, 100, 1), np.arange(0, 100, 1)]
37
field = srf.structured(grid)
38

39
# Estimate variogram from data
40
pos = [grid[0].flatten(), grid[1].flatten()]
41
data = field.flatten()
42
bin_edges = gs.standard_bins(pos)
43
gamma = gs.vario_estimate(pos, data, bin_edges)
44

45
# Fit covariance model to variogram
46
fit_model = gs.Exponential(dim=2)
47
fit_model.fit_variogram(gamma[0], gamma[1])
48

49
# Perform kriging interpolation
50
krige = gs.Krige(fit_model, cond_pos=pos[:, ::100], cond_val=data[::100])
51
krige_field = krige.structured(grid)
52
```
53

54
## Architecture
55

56
GSTools follows a modular architecture with distinct components:
57

58
- **Covariance Models**: Base classes and 20+ built-in models for spatial correlation
59
- **Field Generation**: Classes for unconditional and conditioned random field generation
60
- **Kriging**: Comprehensive kriging interpolation methods (Simple, Ordinary, Universal, External Drift)
61
- **Variogram Estimation**: Empirical variogram calculation and directional analysis
62
- **Utilities**: Export, transformation, normalization, and geometric operations
63

64
This design enables flexible geostatistical workflows from basic random field generation to complex spatial analysis and modeling tasks.
65

66
## Capabilities
67

68
### Covariance Models
69

70
Base classes and 20+ built-in covariance models including Gaussian, Exponential, Matérn, and Truncated Power Law variants. All models support anisotropy, rotation, and spatio-temporal extensions.
71

72
```python { .api }
73
class CovModel:
74
    def __init__(self, dim=3, var=1.0, len_scale=1.0, nugget=0.0, anis=1.0, 
75
                 angles=0.0, integral_scale=None, rescale=None, latlon=False, 
76
                 geo_scale=None, temporal=False, spatial_dim=None, **kwargs): ...
77
    def variogram(self, r): ...
78
    def covariance(self, r): ...
79
    def fit_variogram(self, x_data, y_data, **kwargs): ...
80

81
class Gaussian(CovModel): ...
82
class Exponential(CovModel): ...
83
class Matern(CovModel): 
84
    def __init__(self, nu=1.0, **kwargs): ...
85
```
86

87
[Covariance Models](./covariance-models.md)
88

89
### Field Generation
90

91
Classes for generating unconditional and conditioned spatial random fields, including plurigaussian simulations for categorical fields.
92

93
```python { .api }
94
class SRF:
95
    def __init__(self, model, mean=None, normalizer=None, trend=None, 
96
                 upscaling='no_scaling', generator='RandMeth', **kwargs): ...
97
    def __call__(self, pos, seed=None, mesh_type='unstructured'): ...
98
    def structured(self, pos, **kwargs): ...
99
    def unstructured(self, pos, **kwargs): ...
100

101
class CondSRF(SRF):
102
    def __init__(self, krige, generator='RandMeth', **kwargs): ...
103

104
class PGS:
105
    def __init__(self, dim, fields, **kwargs): ...
106
```
107

108
[Field Generation](./field-generation.md)
109

110
### Kriging
111

112
Comprehensive kriging interpolation methods including Simple, Ordinary, Universal, and External Drift kriging with uncertainty quantification.
113

114
```python { .api }
115
class Krige:
116
    def __init__(self, model, cond_pos, cond_val, drift_functions=None, 
117
                 ext_drift=None, mean=None, unbiased=True, exact=True, 
118
                 cond_err='nugget', pseudo_inv=True): ...
119
    def __call__(self, pos, mesh_type='unstructured', return_var=False): ...
120
    def structured(self, pos, **kwargs): ...
121
    def get_mean(self, **kwargs): ...
122
    def get_variance(self, **kwargs): ...
123
```
124

125
[Kriging](./kriging.md)
126

127
### Variogram Estimation
128

129
Functions for empirical variogram estimation from spatial data including directional analysis and structured/unstructured data support.
130

131
```python { .api }
132
def vario_estimate(pos, field, bin_edges=None, sampling_size=None, 
133
                   estimator='matheron', mesh_type='unstructured'): ...
134
def vario_estimate_axis(pos, field, direction, bin_edges=None, 
135
                        angles_tol=np.pi/8, bandwidth=None): ...
136
def standard_bins(pos, bin_no=50, max_dist=None): ...
137
```
138

139
[Variogram Estimation](./variogram-estimation.md)
140

141
### Utilities
142

143
Comprehensive utility functions including VTK export, geometric operations, field transformations, data normalization, and spatial analysis tools.
144

145
```python { .api }
146
def vtk_export(filename, pos, fields, fieldnames=None): ...
147
def generate_grid(x, y=None, z=None, **kwargs): ...
148
def rotated_main_axes(dim, angles): ...
149

150
# Constants
151
EARTH_RADIUS: float = 6371.0
152
KM_SCALE: float = 6371.0
153
DEGREE_SCALE: float = 57.29577951308232
154
```
155

156
[Utilities](./utilities.md)
157

158
## Error Handling
159

160
GSTools functions may raise the following exceptions:
161

162
- **ValueError**: Invalid parameter values or incompatible dimensions
163
- **RuntimeError**: Numerical computation failures or convergence issues
164
- **NotImplementedError**: Unsupported feature combinations
165
- **ImportError**: Missing optional dependencies for specific functionality
166

167
## Dependencies
168

169
**Required**:
170
- numpy >= 1.20.0
171
- scipy >= 1.1.0
172
- gstools-cython >= 1.0
173
- emcee >= 3.0.0
174
- hankel >= 1.0.0
175
- meshio >= 5.1.0
176
- pyevtk >= 1.1.1
177

178
**Optional**:
179
- matplotlib >= 3.7 (plotting)
180
- pyvista >= 0.40 (3D visualization)
181
- gstools_core >= 1.0.0 (Rust acceleration)