gstools.field.PGS

class gstools.field.PGS(dim, fields)[source]

Bases: object

A class to generate plurigaussian field simulations (PGS).

See e.g. [Ricketts2023] and [Armstrong2011] for more details.

Parameters:

dim (int) – dimension of the field
fields (list or numpy.ndarray) – For dim > 1 a list of spatial random fields (SRFs), with len(fields) == dim. For dim == 1, the SRF can be directly given, instead of a list. This class supports structured and unstructured meshes. All fields must have the same shapes.

Notes

Using plurigaussian fields for conditioning fields is still a beta feature.

References

[Ricketts2023]

Ricketts, E.J., Freeman, B.L., Cleall, P.J. et al. A Statistical Finite Element Method Integrating a Plurigaussian Random Field Generator for Multi-scale Modelling of Solute Transport in Concrete. Transp Porous Med 148, 95–121 (2023) https://doi.org/10.1007/s11242-023-01930-8

[Armstrong2011]

Armstrong, Margaret, et al. Plurigaussian simulations in geosciences. Springer Science & Business Media, 2011. https://doi.org/10.1007/978-3-642-19607-2

Methods

`DecisionTree`(config)	Build and traverse a decision tree for assigning lithotype labels.
`__call__`([lithotypes, tree])	Generate the plurigaussian field via spatial lithotype or decision tree.
`calc_lithotype_axes`(lithotypes_shape)	Calculate the axes on which the lithorypes are defined.
`compute_lithotype`([tree])	Compute lithotype from input SRFs using a `DecisionTree`.
`transform_coords`(lithotypes_shape, pos)	Transform position from correlation coords to L indices.

class DecisionTree(config)[source]

Bases: object

Build and traverse a decision tree for assigning lithotype labels.

This class constructs a tree of DecisionNode and LeafNode instances from a configuration mapping. Once built, it can classify input data by following the decision branches to a leaf action.

Parameters:

config (dict) – Mapping of node IDs to node specifications. Each entry must include:

‘type’: ‘decision’ or ‘leaf’
For decision nodes:
- ‘func’ (callable) and ‘args’ (dict)
- Optional ‘yes_branch’ and ‘no_branch’ keys naming other nodes
For leaf nodes:

Notes

Call build_tree() to link nodes and obtain the root before using decide().
The tree is immutable once built; rebuild to apply a new config.

Methods

`DecisionNode`(func, args[, yes_branch, no_branch])	Internal node that evaluates a condition and routes to child branches.
`LeafNode`(action)	Terminal node that returns a stored action when reached.
`build_tree`()	Construct the decision tree structure from the configuration.
`decide`(data)	Traverse the built tree to make a decision for the given data.

class DecisionNode(func, args, yes_branch=None, no_branch=None)[source]

Bases: object

Internal node that evaluates a condition and routes to child branches.

A DecisionNode wraps a boolean function and two optional branches (yes_branch and no_branch), which may be further DecisionNode or LeafNode instances.

Parameters:

func (callable) – A function that evaluates a condition on the input data. Must accept data as first argument and keyword args.
args (dict) – Keyword arguments to pass to func when called.
yes_branch (DecisionNode or LeafNode, optional) – Node to traverse if func (data, **args) returns True.
no_branch (DecisionNode or LeafNode, optional) – Node to traverse if func (data, **args) returns False.

Methods

decide(data)

Evaluate the decision function and traverse to the next node.

decide(data)[source]

Evaluate the decision function and traverse to the next node.

Parameters:: data (dict) – Feature mapping passed to func.
Returns:: The outcome of the subsequent node’s decide() method, or None if the respective branch is not set.
Return type:: result

class LeafNode(action)[source]

Bases: object

Terminal node that returns a stored action when reached.

A LeafNode represents the outcome of a decision path. Its action value is returned directly by decide()

Parameters:: action (any) – The value to return when this leaf is reached.

Methods

decide(_data)

Return the leaf action, terminating the traversal.

decide(_data)[source]

Return the leaf action, terminating the traversal.

Parameters:: data (dict) – Ignored input data.
Returns:: action – The action value stored in this leaf.
Return type:: any

build_tree()[source]

Construct the decision tree structure from the configuration.

Iterates through the config to create DecisionNode and LeafNode instances, then links decision nodes to their yes/no branches.

Returns:: root – The root node of the constructed decision tree.
Return type:: DecisionNode or LeafNode
Raises:: KeyError – If ‘root’ is not defined in the configuration.

decide(data)[source]

Traverse the built tree to make a decision for the given data.

Parameters:: data (dict) – A mapping of feature names to values, passed to decision functions in each DecisionNode.
Returns:: The action value from the reached LeafNode, or None if a branch is missing.
Return type:: result
Raises:: ValueError – If the tree has not been built (i.e., build_tree() not called).

__call__(lithotypes=None, tree=None)[source]

Generate the plurigaussian field via spatial lithotype or decision tree.

Either a lithotype field or a decision tree config must be provided. If lithotypes is given, map lithotype codes to the PGS via index scaling. If tree is given, build and apply a DecisionTree to assign phase labels.

Parameters:

lithotypes (numpy.ndarray, optional) – dim-dimensional structured lithotype field. Shape may differ from fields, as indices are automatically scaled. Mutually exclusive with tree.
tree (dict, optional) – Configuration dict for constructing a DecisionTree. Must contain node specifications. Mutually exclusive with lithotypes.

Returns:

pgs – Plurigaussian field array: either the mapped lithotype field or the labels assigned by the decision tree, matching the simulation domain.

Return type:

numpy.ndarray

Raises:

ValueError – If neither or both of lithotypes and tree are provided.
ValueError – If lithotypes shape does not match dim or number of fields.
ValueError – If dim != len(fields) when using lithotypes.

calc_lithotype_axes(lithotypes_shape)[source]

Calculate the axes on which the lithorypes are defined.

With the centroid of the correlations of the SRFs at the center, the axes are calculated, which hold all correlations. These axes are used for the lithotypes field.

Parameters:: lithotypes_shape (tuple) – The shape of the lithotypes field.
Returns:: pos_lith – the axes holding all field correlations
Return type:: numpy.ndarray

compute_lithotype(tree=None)[source]

Compute lithotype from input SRFs using a DecisionTree.

If self._tree is not set, a tree configuration must be provided via the tree argument. The method then builds or reuses the DecisionTree and applies it to the coordinates of the plurigaussian fields to assign a lithotype phase at each point.

Parameters:: tree (dict or None, optional) – Configuration for the DecisionTree. If None, self._tree must already be defined. Defaults to None.
Returns:: lithotype – Discrete label array of shape equal to the simulation domain, where each entry is the phase index determined by the tree.
Return type:: numpy.ndarray
Raises:: ValueError – If no DecisionTree is available or if self._dim does not equal the number of provided fields.

transform_coords(lithotypes_shape, pos)[source]

Transform position from correlation coords to L indices.

This is a helper method to get the lithoty pes indices for given correlated field values.

Parameters:

lithotypes_shape (tuple) – The shape of the lithotypes field.
pos (numpy.ndarray) – The position in field coordinates, which will be transformed.

Returns:

pos_trans – the transformed position tuple

Return type:

list