gstools.field

GStools subpackage providing tools for spatial random fields.

Subpackages

generator GStools subpackage providing generators for spatial random fields.
upscaling GStools subpackage providing upscaling routines for the spatial random field.
base GStools subpackage providing a base class for spatial fields.

Spatial Random Field

SRF(model[, mean, upscaling, generator]) A class to generate spatial random fields (SRF).
class gstools.field.SRF(model, mean=0.0, upscaling='no_scaling', generator='RandMeth', **generator_kwargs)[source]

Bases: gstools.field.base.Field

A class to generate spatial random fields (SRF).

Parameters:
  • model (CovModel) – Covariance Model of the spatial random field.
  • mean (float, optional) – mean value of the SRF
  • upscaling (str, optional) –

    Method to be used for upscaling the variance at each point depending on the related element volume. See the point_volumes keyword in the SRF.__call__ routine. At the moment, the following upscaling methods are provided:

    • ”no_scaling” : No upscaling is applied to the variance. See: var_no_scaling
    • ”coarse_graining” : A volume depended variance is calculated by the upscaling technique coarse graining. See: var_coarse_graining

    Default: “no_scaling”

  • generator (str, optional) –

    Name of the field generator to be used. At the moment, the following generators are provided:

    • ”RandMeth” : The Randomization Method. See: RandMeth
    • ”IncomprRandMeth” : The incompressible Randomization Method. This is the original algorithm proposed by Kraichnan 1970 See: IncomprRandMeth
    • ”VectorField” : an alias for “IncomprRandMeth”
    • ”VelocityField” : an alias for “IncomprRandMeth”

    Default: “RandMeth”

  • **generator_kwargs – Keyword arguments that are forwarded to the generator in use. Have a look at the provided generators for further information.
Attributes:
cond_pos

list: The position tuple of the conditions.

cond_val

list: The values of the conditions.

condition

bool: State if conditions ar given.

generator

callable: The generator of the field.

mean

float: The mean of the field.

model

CovModel: The covariance model of the field.

upscaling

str: Name of the upscaling method.

value_type

str: Type of the field values (scalar, vector).

Methods

__call__(pos[, seed, point_volumes, mesh_type]) Generate the spatial random field.
cond_func(*args, **kwargs) Conditioning method applied to the field.
del_condition() Delete Conditions.
mesh(mesh[, points, direction, name]) Generate a field on a given meshio or ogs5py mesh.
plot([field, fig, ax]) Plot the spatial random field.
set_condition([cond_pos, cond_val, krige_type]) Condition a given spatial random field with measurements.
set_generator(generator, **generator_kwargs) Set the generator for the field.
structured(*args, **kwargs) Generate a field on a structured mesh.
to_pyvista([field_select, fieldname]) Create a VTK/PyVista grid of the stored field.
unstructured(*args, **kwargs) Generate a field on an unstructured mesh.
upscaling_func(*args, **kwargs) Upscaling method applied to the field variance.
vtk_export(filename[, field_select, fieldname]) Export the stored field to vtk.
__call__(pos, seed=nan, point_volumes=0.0, mesh_type='unstructured')[source]

Generate the spatial random field.

The field is saved as self.field and is also returned.

Parameters:
  • pos (list) – the position tuple, containing main direction and transversal directions
  • seed (int, optional) – seed for RNG for reseting. Default: keep seed from generator
  • point_volumes (float or numpy.ndarray) – If your evaluation points for the field are coming from a mesh, they are probably representing a certain element volume. This volume can be passed by point_volumes to apply the given variance upscaling. If point_volumes is 0 nothing is changed. Default: 0
  • mesh_type (str) – ‘structured’ / ‘unstructured’
Returns:

field – the SRF
Return type:

numpy.ndarray
cond_func(*args, **kwargs)[source]

Conditioning method applied to the field.

del_condition()[source]

Delete Conditions.

mesh(mesh, points='centroids', direction='xyz', name='field', **kwargs)

Generate a field on a given meshio or ogs5py mesh.

Parameters:
  • mesh (meshio.Mesh or ogs5py.MSH) – The given meshio or ogs5py mesh
  • points (str, optional) – The points to evaluate the field at. Either the “centroids” of the mesh cells (calculated as mean of the cell vertices) or the “points” of the given mesh. Default: “centroids”
  • direction (str, optional) – Here you can state which direction should be choosen for lower dimension. For example, if you got a 2D mesh in xz direction, you have to pass “xz” Default: “xyz”
  • name (str, optional) – Name to store the field in the given mesh as point_data or cell_data. Default: “field”
  • **kwargs – Keyword arguments forwareded to Field.__call__.

Notes

This will store the field in the given mesh under the given name, if a meshio mesh was given.

See: https://github.com/nschloe/meshio

See: Field.__call__

plot(field='field', fig=None, ax=None)

Plot the spatial random field.

Parameters:
  • field (str, optional) – Field that should be plotted. Can be: “field”, “raw_field”, “krige_field”, “err_field” or “krige_var”. Default: “field”
  • fig (Figure or None) – Figure to plot the axes on. If None, a new one will be created. Default: None
  • ax (Axes or None) – Axes to plot on. If None, a new one will be added to the figure. Default: None
set_condition(cond_pos=None, cond_val=None, krige_type='ordinary')[source]

Condition a given spatial random field with measurements.

Parameters:
  • cond_pos (list) – the position tuple of the conditions
  • cond_val (numpy.ndarray) – the values of the conditions
  • krige_type (str, optional) – Used kriging type for conditioning. Either ‘ordinary’ or ‘simple’. Default: ‘ordinary’

Notes

When using “ordinary” as krige_type, the mean attribute of the spatial random field will be overwritten with the estimated mean.

set_generator(generator, **generator_kwargs)[source]

Set the generator for the field.

Parameters:
  • generator (str, optional) – Name of the generator to use for field generation. Default: “RandMeth”
  • **generator_kwargs – keyword arguments that are forwarded to the generator in use.
structured(*args, **kwargs)

Generate a field on a structured mesh.

See Field.__call__

to_pyvista(field_select='field', fieldname='field')

Create a VTK/PyVista grid of the stored field.

Parameters:
  • field_select (str, optional) – Field that should be stored. Can be: “field”, “raw_field”, “krige_field”, “err_field” or “krige_var”. Default: “field”
  • fieldname (str, optional) – Name of the field in the VTK file. Default: “field”
unstructured(*args, **kwargs)

Generate a field on an unstructured mesh.

See Field.__call__

upscaling_func(*args, **kwargs)[source]

Upscaling method applied to the field variance.

vtk_export(filename, field_select='field', fieldname='field')

Export the stored field to vtk.

Parameters:
  • filename (str) – Filename of the file to be saved, including the path. Note that an ending (.vtr or .vtu) will be added to the name.
  • field_select (str, optional) – Field that should be stored. Can be: “field”, “raw_field”, “krige_field”, “err_field” or “krige_var”. Default: “field”
  • fieldname (str, optional) – Name of the field in the VTK file. Default: “field”
cond_pos

The position tuple of the conditions.

Type:list
cond_val

The values of the conditions.

Type:list
condition

State if conditions ar given.

Type:bool
generator

The generator of the field.

Default: RandMeth

Type:callable
mean

The mean of the field.

Type:float
model

The covariance model of the field.

Type:CovModel
upscaling

Name of the upscaling method.

See the point_volumes keyword in the SRF.__call__ routine. Default: “no_scaling”

Type:str
value_type

Type of the field values (scalar, vector).

Type:str