Field Generation

class Field:
    """
    Base class for spatial fields.
    
    Parameters:
    - model (CovModel): Covariance model
    - value_type (str): Field value type ('scalar', 'vector')
    - mean (float or callable): Field mean value or trend function
    - normalizer (Normalizer): Data normalization method
    - trend (callable): Trend function
    - dim (int): Spatial dimension
    """
    def __init__(self, model, value_type='scalar', mean=None, normalizer=None, 
                 trend=None, dim=None): ...
    
    def transform(self, method='log_normal', store=True, **kwargs):
        """
        Apply transformation to field values.
        
        Parameters:
        - method (str): Transformation method
        - store (bool): Store transformed field
        - **kwargs: Transformation parameters
        
        Returns:
        - Transformed field values
        """
    
    def plot(self, field=None, fig=None, ax=None): ...
    def vtk_export(self, filename, **kwargs): ...
    def to_pyvista(self, **kwargs): ...

class SRF(Field):
    """
    Spatial Random Field generator.
    
    Parameters:
    - model (CovModel): Covariance model defining spatial correlation
    - mean (float or callable): Field mean or trend function (default: 0.0)
    - normalizer (Normalizer): Data normalization method
    - trend (callable): Additional trend function  
    - upscaling (str): Upscaling method ('no_scaling', 'coarse_graining')
    - generator (str): Field generation method ('RandMeth', 'VectorField', 'VelocityField', 'IncomprRandMeth', 'Fourier')
    - **generator_kwargs: Generator-specific keyword arguments
    """
    def __init__(self, model, mean=0.0, normalizer=None, trend=None, 
                 upscaling='no_scaling', generator='RandMeth', **generator_kwargs): ...
    
    def __call__(self, pos=None, seed=np.nan, point_volumes=0.0, mesh_type='unstructured', 
                 post_process=True, store=True):
        """
        Generate random field at given positions.
        
        Parameters:  
        - pos (array-like): Field positions (1D, 2D, or 3D coordinates)
        - seed (int): Random seed for reproducibility
        - point_volumes (array-like): Point volumes for upscaling
        - mesh_type (str): Mesh type ('structured', 'unstructured')
        - post_process (bool): Apply post-processing (mean, trend, transformation)
        - store (bool): Store generated field
        
        Returns:
        - Generated field values
        """
    
    def structured(self, pos, **kwargs):
        """
        Generate field on structured grid.
        
        Parameters:
        - pos (list): Grid coordinate arrays [x, y, z]
        - **kwargs: Additional generation parameters
        
        Returns:
        - Generated field on structured grid
        """
    
    def unstructured(self, pos, **kwargs):
        """
        Generate field at unstructured points.
        
        Parameters:
        - pos (array-like): Point coordinates
        - **kwargs: Additional generation parameters
        
        Returns:
        - Generated field values at points
        """
    
    def set_generator(self, generator='RandMeth', **gen_kw):
        """
        Set field generation method.
        
        Parameters:
        - generator (str): Generator type
        - **gen_kw: Generator parameters
        """

class CondSRF(SRF):
    """
    Conditioned Spatial Random Field generator.
    
    Parameters:
    - krige (Krige): Krige instance for conditioning the field
    - generator (str): Field generation method (default: 'RandMeth')
    - **generator_kwargs: Generator-specific keyword arguments
    
    Note: All model, conditioning, and interpolation parameters are configured
    through the provided Krige instance.
    """
    def __init__(self, krige, generator='RandMeth', **generator_kwargs): ...

class PGS(Field):
    """
    Plurigaussian Simulation for categorical fields.
    
    Parameters:
    - dim (int): Dimension of the field
    - fields (list or array): List of spatial random fields (SRFs) for dim > 1, 
                             or single SRF for dim == 1
    
    Note: All fields must have the same shape and support the same mesh types.
    Category assignment is performed through lithotype rules applied to the 
    generated Gaussian fields.
    """
    def __init__(self, dim, fields): ...
    
    def __call__(self, pos, seed=None, **kwargs):
        """
        Generate categorical field.
        
        Parameters:
        - pos (array-like): Field positions
        - seed (int): Random seed
        - **kwargs: Additional generation parameters
        
        Returns:
        - Categorical field values
        """

# Fast, memory-efficient generator
srf = gs.SRF(model, generator='RandMeth', mode_no=1000)

# 2D vector field generation  
srf = gs.SRF(model, generator='VectorField', dim=2)

# Divergence-free velocity field
srf = gs.SRF(model, generator='VelocityField')

# Incompressible field with curl-free property
srf = gs.SRF(model, generator='IncomprRandMeth')

# Periodic field generation
srf = gs.SRF(model, generator='Fourier', periods=[100, 100])

import gstools as gs
import numpy as np

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

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

# Generate at random points
pos = np.random.rand(2, 1000) * 100
field = srf.unstructured(pos)

# Conditioning data
cond_pos = [[10, 50, 80], [20, 60, 90]]  # (x, y) coordinates
cond_val = [1.5, 2.8, 0.9]  # Observed values

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

# Generate conditioned field
field = cond_srf.structured([x, y])

# Import PGS class (requires explicit import)
from gstools.field import PGS

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

# Create PGS
pgs = PGS(model, categories, thresholds)

# Generate categorical field
cat_field = pgs.structured([x, y])

# Generate field and apply transformations
srf = gs.SRF(model)
field = srf.structured([x, y])

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

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

# Box-Cox transformation
boxcox_field = srf.transform('boxcox', lmbda=0.5)

# Custom generator parameters
srf = gs.SRF(
    model, 
    generator='RandMeth',
    mode_no=2000,        # Number of Fourier modes
    sampling='auto',     # Sampling strategy
    verbose=True         # Progress output
)

# Upscaling for point support
srf = gs.SRF(
    model,
    upscaling='var_scaling',  # Variance scaling
    point_volumes=volumes     # Point support volumes
)

# Trend and normalization
from gstools.normalizer import LogNormal
srf = gs.SRF(
    model,
    mean=lambda x, y: x + y,    # Linear trend
    normalizer=LogNormal(),     # Log-normal distribution
    trend=lambda x, y: np.sin(x/10)  # Additional trend
)