gstools.tools¶

GStools subpackage providing miscellaneous tools.

Export¶

`vtk_export`(filename, pos, fields[, mesh_type])	Export a field to vtk.
`vtk_export_structured`(filename, pos, fields)	Export a field to vtk structured rectilinear grid file.
`vtk_export_unstructured`(filename, pos, fields)	Export a field to vtk unstructured grid file.
`to_vtk`(pos, fields[, mesh_type])	Create a VTK/PyVista grid.
`to_vtk_structured`(pos, fields)	Create a vtk structured rectilinear grid from a field.
`to_vtk_unstructured`(pos, fields)	Export a field to vtk structured rectilinear grid file.

Special functions¶

`confidence_scaling`([per])	Scaling of standard deviation to get the desired confidence interval.
`inc_gamma`(s, x)	Calculate the (upper) incomplete gamma function.
`exp_int`(s, x)	Calculate the exponential integral $E_s(x)$ .
`inc_beta`(a, b, x)	Calculate the incomplete Beta function.
`tplstable_cor`(r, len_scale, hurst, alpha)	Calculate the correlation function of the TPLStable model.
`tpl_exp_spec_dens`(k, dim, len_scale, hurst)	Spectal density of the TPLExponential covariance model.
`tpl_gau_spec_dens`(k, dim, len_scale, hurst)	Spectal density of the TPLGaussian covariance model.

Geometric¶

`rotated_main_axes`(dim, angles)	Create list of the main axis defined by the given system rotations.
`set_angles`(dim, angles)	Set the angles for the given dimension.
`set_anis`(dim, anis)	Set the anisotropy ratios for the given dimension.
`no_of_angles`(dim)	Calculate number of rotation angles depending on the dimension.
`rotation_planes`(dim)	Get all 2D sub-planes for rotation.
`givens_rotation`(dim, plane, angle)	Givens rotation matrix in arbitrary dimensions.
`matrix_rotate`(dim, angles)	Create a matrix to rotate points to the target coordinate-system.
`matrix_derotate`(dim, angles)	Create a matrix to derotate points to the initial coordinate-system.
`matrix_isotropify`(dim, anis)	Create a stretching matrix to make things isotrope.
`matrix_anisotropify`(dim, anis)	Create a stretching matrix to make things anisotrope.
`matrix_isometrize`(dim, angles, anis)	Create a matrix to derotate points and make them isotrope.
`matrix_anisometrize`(dim, angles, anis)	Create a matrix to rotate points and make them anisotrope.
`ang2dir`(angles[, dtype, dim])	Convert n-D spherical coordinates to Euclidean direction vectors.
`generate_grid`(pos)	Generate grid from a structured position tuple.
`generate_st_grid`(pos, time[, mesh_type])	Generate spatio-temporal grid from a position tuple and time array.

Misc¶

EARTH_RADIUS

earth radius for WGS84 ellipsoid in km

gstools.tools.ang2dir(angles, dtype=<class 'numpy.float64'>, dim=None)[source]¶

Convert n-D spherical coordinates to Euclidean direction vectors.

Parameters

angles (list of numpy.ndarray) – spherical coordinates given as angles.
dtype (data-type, optional) – The desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence. Default: None
dim (int, optional) – Cut of information above the given dimension. Otherwise, dimension is determined by number of angles Default: None

Returns

the array of direction vectors

Return type

numpy.ndarray

gstools.tools.confidence_scaling(per=0.95)[source]¶

Scaling of standard deviation to get the desired confidence interval.

Parameters: per (float, optional) – Confidence level. The default is 0.95.
Returns: Scale to multiply the standard deviation with.
Return type: float

gstools.tools.exp_int(s, x)[source]¶

Calculate the exponential integral $E_s(x)$ .

Given by: $E_s(x) = \int_1^\infty \frac{e^{-xt}}{t^s}\,\mathrm dt$

Parameters

s (float) – exponent in the integral (should be > -100)
x (numpy.ndarray) – input values

gstools.tools.generate_grid(pos)[source]¶

Generate grid from a structured position tuple.

Parameters: pos (tuple of numpy.ndarray) – The structured position tuple.
Returns: Unstructured position tuple.
Return type: numpy.ndarray

gstools.tools.generate_st_grid(pos, time, mesh_type='unstructured')[source]¶

Generate spatio-temporal grid from a position tuple and time array.

Parameters

pos (tuple of numpy.ndarray) – The (un-)structured position tuple.
time (iterable) – The time array.
mesh_type (str, optional) – ‘structured’ / ‘unstructured’ Default: “unstructured”

Returns

Unstructured spatio-temporal point tuple.

Return type

numpy.ndarray

Notes

Time dimension will be the last one.

gstools.tools.givens_rotation(dim, plane, angle)[source]¶

Givens rotation matrix in arbitrary dimensions.

Parameters

dim (int) – spatial dimension
plane (list of int) – the plane to rotate in, given by the indices of the two defining axes. For example the xy plane is defined by (0,1)
angle (float or list) – the rotation angle in the given plane

Returns

Rotation matrix.

Return type

numpy.ndarray

gstools.tools.inc_beta(a, b, x)[source]¶

Calculate the incomplete Beta function.

Given by: $B(a,b;\,x) = \int_0^x t^{a-1}\,(1-t)^{b-1}\,dt$

Parameters

a (float) – first exponent in the integral
b (float) – second exponent in the integral
x (numpy.ndarray) – input values

gstools.tools.inc_gamma(s, x)[source]¶

Calculate the (upper) incomplete gamma function.

Given by: $\Gamma(s,x) = \int_x^{\infty} t^{s-1}\,e^{-t}\,{\rm d}t$

Parameters

s (float) – exponent in the integral
x (numpy.ndarray) – input values

gstools.tools.matrix_anisometrize(dim, angles, anis)[source]¶

Create a matrix to rotate points and make them anisotrope.

Parameters

dim (int) – spatial dimension
angles (float or list) – the rotation angles of the target coordinate-system
anis (list of float) – the anisotropy of length scales along the transversal directions

Returns

Transformation matrix.

Return type

numpy.ndarray

gstools.tools.matrix_anisotropify(dim, anis)[source]¶

Create a stretching matrix to make things anisotrope.

Parameters

dim (int) – spatial dimension
anis (list of float) – the anisotropy of length scales along the transversal directions

Returns

Stretching matrix.

Return type

numpy.ndarray

gstools.tools.matrix_derotate(dim, angles)[source]¶

Create a matrix to derotate points to the initial coordinate-system.

Parameters

dim (int) – spatial dimension
angles (float or list) – the rotation angles of the target coordinate-system

Returns

Rotation matrix.

Return type

numpy.ndarray

gstools.tools.matrix_isometrize(dim, angles, anis)[source]¶

Create a matrix to derotate points and make them isotrope.

Parameters

dim (int) – spatial dimension
angles (float or list) – the rotation angles of the target coordinate-system
anis (list of float) – the anisotropy of length scales along the transversal directions

Returns

Transformation matrix.

Return type

numpy.ndarray

gstools.tools.matrix_isotropify(dim, anis)[source]¶

Create a stretching matrix to make things isotrope.

Parameters

dim (int) – spatial dimension
anis (list of float) – the anisotropy of length scales along the transversal directions

Returns

Stretching matrix.

Return type

numpy.ndarray

gstools.tools.matrix_rotate(dim, angles)[source]¶

Create a matrix to rotate points to the target coordinate-system.

Parameters

dim (int) – spatial dimension
angles (float or list) – the rotation angles of the target coordinate-system

Returns

Rotation matrix.

Return type

numpy.ndarray

gstools.tools.no_of_angles(dim)[source]¶

Calculate number of rotation angles depending on the dimension.

Parameters: dim (int) – spatial dimension
Returns: Number of angles.
Return type: int

gstools.tools.rotated_main_axes(dim, angles)[source]¶

Create list of the main axis defined by the given system rotations.

Parameters

dim (int) – spatial dimension
angles (float or list) – the rotation angles of the target coordinate-system

Returns

Main axes of the target coordinate-system.

Return type

numpy.ndarray

gstools.tools.rotation_planes(dim)[source]¶

Get all 2D sub-planes for rotation.

Parameters: dim (int) – spatial dimension
Returns: All 2D sub-planes for rotation.
Return type: list of tuple of int

gstools.tools.set_angles(dim, angles)[source]¶

Set the angles for the given dimension.

Parameters

dim (int) – spatial dimension
angles (float or list) – the angles of the SRF

Returns

angles – the angles fitting to the dimension

Return type

float

Notes

If too few angles are given, they are filled up with 0.

gstools.tools.set_anis(dim, anis)[source]¶

Set the anisotropy ratios for the given dimension.

Parameters

dim (int) – spatial dimension
anis (list of float) – the anisotropy of length scales along the transversal directions

Returns

anis – the anisotropy of length scales fitting the dimensions

Return type

list of float

Notes

If too few anisotropy ratios are given, they are filled up with 1.

gstools.tools.to_vtk(pos, fields, mesh_type='unstructured')[source]¶

Create a VTK/PyVista grid.

Parameters

pos (list) – the position tuple, containing main direction and transversal directions
fields (dict or numpy.ndarray) – [Un]structured fields to be saved. Either a single numpy array as returned by SRF, or a dictionary of fields with theirs names as keys.
mesh_type (str, optional) – ‘structured’ / ‘unstructured’. Default: structured

Returns

This will return a PyVista object for the given field data in its appropriate type. Structured meshes will return a pyvista.RectilinearGrid and unstructured meshes will return an pyvista.UnstructuredGrid object.

Return type

pyvista.RectilinearGrid or pyvista.UnstructuredGrid

gstools.tools.to_vtk_structured(pos, fields)[source]¶

Create a vtk structured rectilinear grid from a field.

Parameters

pos (list) – the position tuple, containing main direction and transversal directions
fields (dict or numpy.ndarray) – Structured fields to be saved. Either a single numpy array as returned by SRF, or a dictionary of fields with theirs names as keys.

Returns

A PyVista rectilinear grid of the structured field data. Data arrays live on the point data of this PyVista dataset.

Return type

pyvista.RectilinearGrid

gstools.tools.to_vtk_unstructured(pos, fields)[source]¶

Export a field to vtk structured rectilinear grid file.

Parameters

pos (list) – the position tuple, containing main direction and transversal directions
fields (dict or numpy.ndarray) – Unstructured fields to be saved. Either a single numpy array as returned by SRF, or a dictionary of fields with theirs names as keys.

Returns

A PyVista unstructured grid of the unstructured field data. Data arrays live on the point data of this PyVista dataset. This is essentially a point cloud with no topology.

Return type

pyvista.UnstructuredGrid

gstools.tools.tpl_exp_spec_dens(k, dim, len_scale, hurst, len_low=0.0)[source]¶

Spectal density of the TPLExponential covariance model.

Parameters

k (float) – Radius of the phase: $k=\left\Vert\mathbf{k}\right\Vert$
dim (int) – Dimension of the model.
len_scale (float) – Length scale of the model.
hurst (float) – Hurst coefficient of the power law.
len_low (float, optional) – The lower length scale truncation of the model. Default: 0.0

Returns

spectal density of the TPLExponential model

Return type

float

gstools.tools.tpl_gau_spec_dens(k, dim, len_scale, hurst, len_low=0.0)[source]¶

Spectal density of the TPLGaussian covariance model.

Parameters

k (float) – Radius of the phase: $k=\left\Vert\mathbf{k}\right\Vert$
dim (int) – Dimension of the model.
len_scale (float) – Length scale of the model.
hurst (float) – Hurst coefficient of the power law.
len_low (float, optional) – The lower length scale truncation of the model. Default: 0.0

Returns

spectal density of the TPLExponential model

Return type

float

gstools.tools.tplstable_cor(r, len_scale, hurst, alpha)[source]¶

Calculate the correlation function of the TPLStable model.

Given by the following correlation function:

$\rho(r) = \frac{2H}{\alpha} \cdot E_{1+\frac{2H}{\alpha}} \left(\left(\frac{r}{\ell}\right)^{\alpha} \right)$

Parameters

r (numpy.ndarray) – input values
len_scale (float) – length-scale of the model.
hurst (float) – Hurst coefficient of the power law.
alpha (float, optional) – Shape parameter of the stable model.

gstools.tools.vtk_export(filename, pos, fields, mesh_type='unstructured')[source]¶

Export a 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.
pos (list) – the position tuple, containing main direction and transversal directions
fields (dict or numpy.ndarray) – [Un]structured fields to be saved. Either a single numpy array as returned by SRF, or a dictionary of fields with theirs names as keys.
mesh_type (str, optional) – ‘structured’ / ‘unstructured’. Default: structured

gstools.tools.vtk_export_structured(filename, pos, fields)[source]¶

Export a field to vtk structured rectilinear grid file.

Parameters

filename (str) – Filename of the file to be saved, including the path. Note that an ending (.vtr) will be added to the name.
pos (list) – the position tuple, containing main direction and transversal directions
fields (dict or numpy.ndarray) – Structured fields to be saved. Either a single numpy array as returned by SRF, or a dictionary of fields with theirs names as keys.

gstools.tools.vtk_export_unstructured(filename, pos, fields)[source]¶

Export a field to vtk unstructured grid file.

Parameters

filename (str) – Filename of the file to be saved, including the path. Note that an ending (.vtu) will be added to the name.
pos (list) – the position tuple, containing main direction and transversal directions
fields (dict or numpy.ndarray) – Unstructured fields to be saved. Either a single numpy array as returned by SRF, or a dictionary of fields with theirs names as keys.

gstools.tools.EARTH_RADIUS = 6371.0¶

earth radius for WGS84 ellipsoid in km

Type: float