gstools.field.SRF

class gstools.field.SRF(model, mean=0.0, normalizer=None, trend=None, upscaling='no_scaling', generator='RandMeth', **generator_kwargs)[source]

Bases: Field

A class to generate spatial random fields (SRF).

Parameters

  • model (CovModel) – Covariance Model of the spatial random field.

  • mean (float or callable, optional) – Mean of the SRF (in normal form). Could also be a callable. The default is 0.0.

  • normalizer (None or Normalizer, optional) – Normalizer to be applied to the SRF to transform the field values. The default is None.

  • trend (None or float or callable, optional) – Trend of the SRF (in transformed form). If no normalizer is applied, this behaves equal to ‘mean’. The default is None.

  • 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 or Generator, optional) – Name or class 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
all_fields

list: All fields as stacked list.

dim

int: Dimension of the field.

field_names

list: Names of present fields.

field_shape

tuple: The shape of the field.

generator

callable: The generator of the field.

latlon

bool: Whether the field depends on geographical coords.

mean

float or callable: The mean of the field.

mesh_type

str: The mesh type of the field.

model

CovModel: The covariance model of the field.

name

str: The name of the class.

normalizer

Normalizer: Normalizer of the field.

pos

tuple: The position tuple of the field.

temporal

bool: Whether the field depends on time.

trend

float or callable: The trend 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, ...])

Generate the spatial random field.

delete_fields([select])

Delete selected fields.

get_store_config(store[, default, fld_cnt])

Get storage configuration from given selection.

mesh(mesh[, points, direction, name])

Generate a field on a given meshio, ogs5py or PyVista mesh.

plot([field, fig, ax])

Plot the spatial random field.

post_field(field[, name, process, save])

Postprocessing field values.

pre_pos([pos, mesh_type, info])

Preprocessing positions and mesh_type.

set_generator(generator, **generator_kwargs)

Set the generator for the field.

set_pos(pos[, mesh_type, info])

Set positions and mesh_type.

structured(*args, **kwargs)

Generate a field on a structured mesh.

to_pyvista([field_select, fieldname])

Create a VTK/PyVista grid of the stored field.

transform(method[, field, store, process])

Apply field transformation.

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=None, seed=nan, point_volumes=0.0, mesh_type='unstructured', post_process=True, store=True)[source]

Generate the spatial random field.

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

Parameters

  • pos (list, optional) – the position tuple, containing main direction and transversal directions

  • seed (int, optional) – seed for RNG for resetting. 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’

  • post_process (bool, optional) – Whether to apply mean, normalizer and trend to the field. Default: True

  • store (str or bool, optional) – Whether to store field (True/False) with default name or with specified name. The default is True for default name “field”.

Returns

field – the SRF

Return type

numpy.ndarray

delete_fields(select=None)

Delete selected fields.

get_store_config(store, default=None, fld_cnt=None)

Get storage configuration from given selection.

Parameters

  • store (str or bool or list, optional) – Whether to store fields (True/False) with default names or with specified names. The default is True for default names.

  • default (str or list, optional) – Default field names. The default is “field”.

  • fld_cnt (None or int, optional) – Number of fields when using lists. The default is None.

Returns

  • name (str or list) – Name(s) of field.

  • save (bool or list) – Whether to save field(s).

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

Generate a field on a given meshio, ogs5py or PyVista mesh.

Parameters

  • mesh (meshio.Mesh or ogs5py.MSH or PyVista mesh) – The given 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 or list, optional) – Here you can state which direction should be chosen for lower dimension. For example, if you got a 2D mesh in xz direction, you have to pass “xz”. By default, all directions are used. One can also pass a list of indices. Default: “all”

  • name (str or list of str, optional) – Name(s) to store the field(s) in the given mesh as point_data or cell_data. If to few names are given, digits will be appended. Default: “field”

  • **kwargs – Keyword arguments forwarded to __call__.

Notes

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

See:
plot(field='field', fig=None, ax=None, **kwargs)

Plot the spatial random field.

Parameters

  • field (str, optional) – Field that should be plotted. 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

  • **kwargs – Forwarded to the plotting routine.

post_field(field, name='field', process=True, save=True)

Postprocessing field values.

Parameters

  • field (numpy.ndarray) – Field values.

  • name (str, optional) – Name. to store the field. The default is “field”.

  • process (bool, optional) – Whether to process field to apply mean, normalizer and trend. The default is True.

  • save (bool, optional) – Whether to store the field under the given name. The default is True.

Returns

field – Processed field values.

Return type

numpy.ndarray

pre_pos(pos=None, mesh_type='unstructured', info=False)

Preprocessing positions and mesh_type.

Parameters

  • pos (iterable) – the position tuple, containing main direction and transversal directions

  • mesh_type (str, optional) – ‘structured’ / ‘unstructured’ Default: “unstructured”

  • info (bool, optional) – Whether to return information

Returns

  • iso_pos ((d, n), numpy.ndarray) – Isometrized position tuple.

  • shape (tuple) – Shape of the resulting field.

  • info (dict, optional) – Information about settings.

Warning

When setting a new position tuple that differs from the present one, all stored fields will be deleted.

set_generator(generator, **generator_kwargs)[source]

Set the generator for the field.

Parameters

  • generator (str or Generator, optional) – Name or class of the field generator to be used. Default: “RandMeth”

  • **generator_kwargs – keyword arguments that are forwarded to the generator in use.

set_pos(pos, mesh_type='unstructured', info=False)

Set positions and mesh_type.

Parameters

  • pos (iterable) – the position tuple, containing main direction and transversal directions

  • mesh_type (str, optional) – ‘structured’ / ‘unstructured’ Default: “unstructured”

  • info (bool, optional) – Whether to return information

Returns

info – Information about settings.

Return type

dict, optional

Warning

When setting a new position tuple that differs from the present one, all stored fields will be deleted.

structured(*args, **kwargs)

Generate a field on a structured mesh.

See __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”

transform(method, field='field', store=True, process=False, **kwargs)

Apply field transformation.

Parameters

  • method (str) – Method to use. See gstools.transform for available transformations.

  • field (str, optional) – Name of field to be transformed. The default is “field”.

  • store (str or bool, optional) – Whether to store field inplace (True/False) or under a given name. The default is True.

  • process (bool, optional) – Whether to process in/out fields with trend, normalizer and mean of given Field instance. The default is False.

  • **kwargs – Keyword arguments forwarded to selected method.

Raises

ValueError – When method is unknown.

Returns

Transformed field.

Return type

numpy.ndarray

unstructured(*args, **kwargs)

Generate a field on an unstructured mesh.

See __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”

property all_fields

All fields as stacked list.

Type

list

default_field_names = ['field']

Default field names.

Type

list

property dim

Dimension of the field.

Type

int

property field_names

Names of present fields.

Type

list

property field_shape

The shape of the field.

Type

tuple

property generator

The generator of the field.

Default: RandMeth

Type

callable

property latlon

Whether the field depends on geographical coords.

Type

bool

property mean

The mean of the field.

Type

float or callable

property mesh_type

The mesh type of the field.

Type

str

property model

The covariance model of the field.

Type

CovModel

property name

The name of the class.

Type

str

property normalizer

Normalizer of the field.

Type

Normalizer

property pos

The position tuple of the field.

Type

tuple

property temporal

Whether the field depends on time.

Type

bool

property trend

The trend of the field.

Type

float or callable

property upscaling

Name of the upscaling method.

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

Type

str

valid_value_types = ['scalar', 'vector']

valid field value types.

Type

list of str

property value_type

Type of the field values (scalar, vector).

Type

str