0
# Field Generation
1

2
Field generation classes create spatial random fields, conditioned fields, and categorical simulations based on covariance models. These classes form the core of GSTools' spatial modeling capabilities.
3

4
## Capabilities
5

6
### Base Field Class
7

8
Foundation class providing common functionality for all field types including transformation, plotting, and export capabilities.
9

10
```python { .api }
11
class Field:
12
    """
13
    Base class for spatial fields.
14
    
15
    Parameters:
16
    - model (CovModel): Covariance model
17
    - value_type (str): Field value type ('scalar', 'vector')
18
    - mean (float or callable): Field mean value or trend function
19
    - normalizer (Normalizer): Data normalization method
20
    - trend (callable): Trend function
21
    - dim (int): Spatial dimension
22
    """
23
    def __init__(self, model, value_type='scalar', mean=None, normalizer=None, 
24
                 trend=None, dim=None): ...
25
    
26
    def transform(self, method='log_normal', store=True, **kwargs):
27
        """
28
        Apply transformation to field values.
29
        
30
        Parameters:
31
        - method (str): Transformation method
32
        - store (bool): Store transformed field
33
        - **kwargs: Transformation parameters
34
        
35
        Returns:
36
        - Transformed field values
37
        """
38
    
39
    def plot(self, field=None, fig=None, ax=None): ...
40
    def vtk_export(self, filename, **kwargs): ...
41
    def to_pyvista(self, **kwargs): ...
42
```
43

44
### Spatial Random Field (SRF)
45

46
Primary class for generating unconditional spatial random fields with various generators and upscaling methods.
47

48
```python { .api }
49
class SRF(Field):
50
    """
51
    Spatial Random Field generator.
52
    
53
    Parameters:
54
    - model (CovModel): Covariance model defining spatial correlation
55
    - mean (float or callable): Field mean or trend function (default: 0.0)
56
    - normalizer (Normalizer): Data normalization method
57
    - trend (callable): Additional trend function  
58
    - upscaling (str): Upscaling method ('no_scaling', 'coarse_graining')
59
    - generator (str): Field generation method ('RandMeth', 'VectorField', 'VelocityField', 'IncomprRandMeth', 'Fourier')
60
    - **generator_kwargs: Generator-specific keyword arguments
61
    """
62
    def __init__(self, model, mean=0.0, normalizer=None, trend=None, 
63
                 upscaling='no_scaling', generator='RandMeth', **generator_kwargs): ...
64
    
65
    def __call__(self, pos=None, seed=np.nan, point_volumes=0.0, mesh_type='unstructured', 
66
                 post_process=True, store=True):
67
        """
68
        Generate random field at given positions.
69
        
70
        Parameters:  
71
        - pos (array-like): Field positions (1D, 2D, or 3D coordinates)
72
        - seed (int): Random seed for reproducibility
73
        - point_volumes (array-like): Point volumes for upscaling
74
        - mesh_type (str): Mesh type ('structured', 'unstructured')
75
        - post_process (bool): Apply post-processing (mean, trend, transformation)
76
        - store (bool): Store generated field
77
        
78
        Returns:
79
        - Generated field values
80
        """
81
    
82
    def structured(self, pos, **kwargs):
83
        """
84
        Generate field on structured grid.
85
        
86
        Parameters:
87
        - pos (list): Grid coordinate arrays [x, y, z]
88
        - **kwargs: Additional generation parameters
89
        
90
        Returns:
91
        - Generated field on structured grid
92
        """
93
    
94
    def unstructured(self, pos, **kwargs):
95
        """
96
        Generate field at unstructured points.
97
        
98
        Parameters:
99
        - pos (array-like): Point coordinates
100
        - **kwargs: Additional generation parameters
101
        
102
        Returns:
103
        - Generated field values at points
104
        """
105
    
106
    def set_generator(self, generator='RandMeth', **gen_kw):
107
        """
108
        Set field generation method.
109
        
110
        Parameters:
111
        - generator (str): Generator type
112
        - **gen_kw: Generator parameters
113
        """
114
```
115

116
### Conditioned Spatial Random Field (CondSRF)
117

118
Extension of SRF for generating fields conditioned on observed data points using kriging interpolation.
119

120
```python { .api }
121
class CondSRF(SRF):
122
    """
123
    Conditioned Spatial Random Field generator.
124
    
125
    Parameters:
126
    - krige (Krige): Krige instance for conditioning the field
127
    - generator (str): Field generation method (default: 'RandMeth')
128
    - **generator_kwargs: Generator-specific keyword arguments
129
    
130
    Note: All model, conditioning, and interpolation parameters are configured
131
    through the provided Krige instance.
132
    """
133
    def __init__(self, krige, generator='RandMeth', **generator_kwargs): ...
134
```
135

136
### Plurigaussian Simulation (PGS)
137

138
Categorical field simulation using Gaussian random fields and threshold rules to generate discrete categories.
139

140
```python { .api }
141
class PGS(Field):
142
    """
143
    Plurigaussian Simulation for categorical fields.
144
    
145
    Parameters:
146
    - dim (int): Dimension of the field
147
    - fields (list or array): List of spatial random fields (SRFs) for dim > 1, 
148
                             or single SRF for dim == 1
149
    
150
    Note: All fields must have the same shape and support the same mesh types.
151
    Category assignment is performed through lithotype rules applied to the 
152
    generated Gaussian fields.
153
    """
154
    def __init__(self, dim, fields): ...
155
    
156
    def __call__(self, pos, seed=None, **kwargs):
157
        """
158
        Generate categorical field.
159
        
160
        Parameters:
161
        - pos (array-like): Field positions
162
        - seed (int): Random seed
163
        - **kwargs: Additional generation parameters
164
        
165
        Returns:
166
        - Categorical field values
167
        """
168
```
169

170
## Generator Types
171

172
### Random Method (RandMeth)
173

174
Default generator using randomization method for efficient field generation.
175

176
```python
177
# Fast, memory-efficient generator
178
srf = gs.SRF(model, generator='RandMeth', mode_no=1000)
179
```
180

181
### Vector Field
182

183
Generate vector fields with specified dimensions.
184

185
```python
186
# 2D vector field generation  
187
srf = gs.SRF(model, generator='VectorField', dim=2)
188
```
189

190
### Velocity Field
191

192
Generate incompressible velocity fields.
193

194
```python
195
# Divergence-free velocity field
196
srf = gs.SRF(model, generator='VelocityField')
197
```
198

199
### Incompressible Random Method
200

201
Generate incompressible scalar fields.
202

203
```python
204
# Incompressible field with curl-free property
205
srf = gs.SRF(model, generator='IncomprRandMeth')
206
```
207

208
### Fourier Method
209

210
Direct Fourier transform method for periodic boundary conditions.
211

212
```python
213
# Periodic field generation
214
srf = gs.SRF(model, generator='Fourier', periods=[100, 100])
215
```
216

217
## Usage Examples
218

219
### Basic Random Field Generation
220

221
```python
222
import gstools as gs
223
import numpy as np
224

225
# Define model and create SRF
226
model = gs.Gaussian(dim=2, var=1.0, len_scale=10.0)
227
srf = gs.SRF(model, mean=2.0, seed=12345)
228

229
# Generate on structured grid
230
x = y = np.arange(0, 100, 1.0)
231
field = srf.structured([x, y])
232

233
# Generate at random points
234
pos = np.random.rand(2, 1000) * 100
235
field = srf.unstructured(pos)
236
```
237

238
### Conditioned Field Generation
239

240
```python
241
# Conditioning data
242
cond_pos = [[10, 50, 80], [20, 60, 90]]  # (x, y) coordinates
243
cond_val = [1.5, 2.8, 0.9]  # Observed values
244

245
# Create conditioned field
246
cond_srf = gs.CondSRF(model, cond_pos, cond_val)
247

248
# Generate conditioned field
249
field = cond_srf.structured([x, y])
250
```
251

252
### Categorical Field Simulation
253

254
```python
255
# Import PGS class (requires explicit import)
256
from gstools.field import PGS
257

258
# Define categories and thresholds
259
categories = ['sand', 'clay', 'rock']
260
thresholds = [-0.5, 0.5]  # Two thresholds for three categories
261

262
# Create PGS
263
pgs = PGS(model, categories, thresholds)
264

265
# Generate categorical field
266
cat_field = pgs.structured([x, y])
267
```
268

269
### Field Transformation
270

271
```python
272
# Generate field and apply transformations
273
srf = gs.SRF(model)
274
field = srf.structured([x, y])
275

276
# Log-normal transformation
277
log_field = srf.transform('log_normal', mean=1.0, var=0.5)
278

279
# Binary transformation  
280
binary_field = srf.transform('binary', threshold=0.0)
281

282
# Box-Cox transformation
283
boxcox_field = srf.transform('boxcox', lmbda=0.5)
284
```
285

286
### Advanced Generation Options
287

288
```python
289
# Custom generator parameters
290
srf = gs.SRF(
291
    model, 
292
    generator='RandMeth',
293
    mode_no=2000,        # Number of Fourier modes
294
    sampling='auto',     # Sampling strategy
295
    verbose=True         # Progress output
296
)
297

298
# Upscaling for point support
299
srf = gs.SRF(
300
    model,
301
    upscaling='var_scaling',  # Variance scaling
302
    point_volumes=volumes     # Point support volumes
303
)
304

305
# Trend and normalization
306
from gstools.normalizer import LogNormal
307
srf = gs.SRF(
308
    model,
309
    mean=lambda x, y: x + y,    # Linear trend
310
    normalizer=LogNormal(),     # Log-normal distribution
311
    trend=lambda x, y: np.sin(x/10)  # Additional trend
312
)
313
```
314

315
## Field Properties and Methods
316

317
Generated fields provide the following key properties:
318

319
- **pos**: Field position coordinates
320
- **field**: Generated field values
321
- **field_names**: Names of generated fields
322
- **field_shape**: Shape of field array
323
- **mesh_type**: Type of spatial mesh
324
- **model**: Associated covariance model
325
- **mean**: Field mean value
326
- **normalizer**: Applied normalization
327
- **trend**: Applied trend function
328

329
Key methods include:
330

331
- **Generation**: `__call__()`, `structured()`, `unstructured()`
332
- **Transformation**: `transform()`
333
- **Visualization**: `plot()`
334
- **Export**: `vtk_export()`, `to_pyvista()`
335
- **Configuration**: `set_generator()`