LoopStructural.GeologicalModel#

class LoopStructural.GeologicalModel(*args)#

Bases: object

A geological model is the recipe for building a 3D model and can include the rescaling of the model between 0 and 1.

features#

Contains all features youngest to oldest

Type:: list

feature_name_index#

maps feature name to the list index of the features

Type:: dict

data#

the dataframe used for building the geological model

Type:: pandas dataframe

nsteps#

the number of steps x,y,z to evaluate the model

Type:: tuple/np.array(3,dtype=int)

origin#

the origin of the model box

Type:: tuple/np.array(3,dtype=doubles)

parameters#

a dictionary tracking the parameters used to build the model

Type:: dict

Parameters:

bounding_box (BoundingBox) – the bounding box of the model
origin (np.array(3,dtype=doubles)) – the origin of the model
maximum (np.array(3,dtype=doubles)) – the maximum of the model

Examples

Demo data

>>> from LoopStructural.datasets import load_claudius
>>> from LoopStructural import GeologicalModel

>>> data, bb = load_claudius()

>>> model = GeologicalModel(bb[:,0],bb[:,1]
>>> model.set_model_data(data)
>>> model.create_and_add_foliation('strati')

>>> y = np.linspace(model.bounding_box[0, 1], model.bounding_box[1, 1],
                nsteps[1])
>>> z = np.linspace(model.bounding_box[1, 2], model.bounding_box[0, 2],
                nsteps[2])
>>> xx, yy, zz = np.meshgrid(x, y, z, indexing='ij')
>>> xyz = np.array([xx.flatten(), yy.flatten(), zz.flatten()]).T
>>> model.evaluate_feature_value('strati',xyz,scale=False)

__init__(*args)#

Parameters:

bounding_box (BoundingBox) – the bounding box of the model
origin (np.array(3,dtype=doubles)) – the origin of the model
maximum (np.array(3,dtype=doubles)) – the maximum of the model

Examples

Demo data

>>> from LoopStructural.datasets import load_claudius
>>> from LoopStructural import GeologicalModel

>>> data, bb = load_claudius()

>>> model = GeologicalModel(bb[:,0],bb[:,1]
>>> model.set_model_data(data)
>>> model.create_and_add_foliation('strati')

>>> y = np.linspace(model.bounding_box[0, 1], model.bounding_box[1, 1],
                nsteps[1])
>>> z = np.linspace(model.bounding_box[1, 2], model.bounding_box[0, 2],
                nsteps[2])
>>> xx, yy, zz = np.meshgrid(x, y, z, indexing='ij')
>>> xyz = np.array([xx.flatten(), yy.flatten(), zz.flatten()]).T
>>> model.evaluate_feature_value('strati',xyz,scale=False)

Methods

`__init__`(*args)
`add_onlap_unconformity`(feature, value)	Use an existing feature to add an unconformity to the model.
`add_unconformity`(feature, value)	Use an existing feature to add an unconformity to the model.
`create_and_add_domain_fault`(...[, ...])
`create_and_add_fault`(fault_name, displacement, *)
`create_and_add_fold_frame`(fold_frame_name, *)
`create_and_add_folded_fold_frame`(...[, ...])
`create_and_add_folded_foliation`(...[, ...])	Create a folded foliation field from data and a fold frame
`create_and_add_foliation`(series_surface_name, *)
`create_and_add_intrusion`(intrusion_name, ...)
`data_for_feature`(feature_name)	Get all of the data associated with a geological feature
`evaluate_fault_displacements`(points[, scale])	Evaluate the fault displacement magnitude at each location
`evaluate_feature_gradient`(feature_name, xyz)	Evaluate the gradient of the geological feature at a location
`evaluate_feature_value`(feature_name, xyz[, ...])	Evaluate the scalar value of the geological feature given the name at locations xyz
`evaluate_model`(xyz, *[, scale])	Evaluate the stratigraphic id at each location
`evaluate_model_gradient`(points, *[, scale])	Evaluate the gradient of the stratigraphic column at each location
`fault_names`()	Get name of all faults in the model
`feature_names`()
`from_file`(file)	Load a geological model from file
`from_processor`(processor)	Builds a model from a `LoopStructural.modelling.input.ProcessInputData` object This object stores the observations and order of the geological features
`get_block_model`([name])
`get_fault_surfaces`([faults])
`get_feature_by_name`(feature_name)	Returns a feature from the mode given a name
`get_stratigraphic_surfaces`([units, bottoms])
`prepare_data`(data)
`regular_grid`(*[, nsteps, shuffle, rescale, ...])	Return a regular grid within the model bounding box
`rescale`(points, *[, inplace])	Convert from model scale to real world scale - in the future this should also do transformations?
`save`(filename[, block_model, ...])
`scale`(points, *[, inplace])	Take points in UTM coordinates and reproject into scaled model space
`set_model_data`(data)
`set_stratigraphic_column`(stratigraphic_column)	Adds a stratigraphic column to the model
`stratigraphic_ids`()	Return a list of all stratigraphic ids in the model
`to_dict`()	Convert the geological model to a json string
`to_file`(file)	Save a model to a pickle file requires dill
`update`([verbose, progressbar])

Attributes

`data`
`dtm`
`faults`	Get all of the fault features in the model
`faults_displacement_magnitude`
`intrusions`
`series`
`stratigraphic_column`	Get the stratigraphic column of the model

add_onlap_unconformity(feature: GeologicalFeature, value: float) → GeologicalFeature#

Use an existing feature to add an unconformity to the model.

Parameters:

feature (GeologicalFeature) – existing geological feature
value (float) – scalar value of isosurface that represents

Returns:

unconformity_feature (GeologicalFeature) – the created unconformity

add_unconformity(feature: GeologicalFeature, value: float) → UnconformityFeature#

Use an existing feature to add an unconformity to the model.

Parameters:

feature (GeologicalFeature) – existing geological feature
value (float) – scalar value of isosurface that represents

Returns:

unconformity (GeologicalFeature) – unconformity feature

create_and_add_domain_fault(fault_surface_data, *, nelements=10000, interpolatortype='FDI', **kwargs)#

Parameters:: fault_surface_data (string) – name of the domain fault data in the data frame
Returns:: domain_Fault (GeologicalFeature) – the created domain fault

Notes

LoopStructural.GeologicalModel.get_interpolator()

create_and_add_fault(fault_name: str, displacement: float, *, fault_data: DataFrame | None = None, interpolatortype='FDI', tol=None, fault_slip_vector=None, fault_normal_vector=None, fault_center=None, major_axis=None, minor_axis=None, intermediate_axis=None, faultfunction='BaseFault', faults=[], force_mesh_geometry: bool = False, points: bool = False, fault_buffer=0.2, fault_trace_anisotropy=0.0, fault_dip=90, fault_dip_anisotropy=0.0, fault_pitch=None, **kwargs)#

Parameters:

fault_name (string) – name of the fault surface data in the dataframe
displacement (displacement magnitude) – displacement magnitude of the fault, in model units
fault_data (pd.DataFrame, optional) – data frame containing the fault data, if not specified uses the model data
major_axis ([type], optional) – [description], by default None
minor_axis ([type], optional) – [description], by default None
intermediate_axis ([type], optional) – [description], by default None
kwargs (additional kwargs for Fault and interpolators)

Returns:

fault (FaultSegment) – created fault

Notes

LoopStructural.GeologicalModel.get_interpolator()
LoopStructural.modelling.features.builders.FaultBuilder
LoopStructural.modelling.features.builders.FaultBuilder.setup()

create_and_add_fold_frame(fold_frame_name: str, *, fold_frame_data=None, interpolatortype='FDI', nelements=1000, tol=None, buffer=0.1, **kwargs)#

Parameters:

fold_frame_name (string) – unique string in feature_name column
fold_frame_data (pandas data frame) – if not specified uses the model data
interpolatortype (str) – the type of interpolator to use, default is ‘FDI’
nelements (int) – the number of elements to use in the fold frame
tol (float, optional) – tolerance for the solver
buffer (float) – buffer to add to the bounding box of the fold frame
**kwargs (dict) – additional parameters to be passed to the LoopStructural.modelling.features.builders.StructuralFrameBuilder and LoopStructural.modelling.features.builders.StructuralFrameBuilder.setup() and the interpolator, such as domain or tol

Returns:

fold_frame (FoldFrame) – the created fold frame

create_and_add_folded_fold_frame(fold_frame_name: str, *, fold_frame_data: DataFrame | None = None, interpolatortype='FDI', nelements=10000, fold_frame=None, tol=None, **kwargs)#

Parameters:

fold_frame_name (string) – name of the feature to be added
fold_frame_data (pandas data frame, optional) – data frame containing the fold frame data, if not specified uses the model data
interpolatortype (str) – the type of interpolator to use, default is ‘FDI’ (unused) 5/6/2025
fold_frame (StructuralFrame, optional) – the fold frame for the fold if not specified uses last feature added
nelements (int) – the number of elements to use in the fold frame
tol (float, optional) – tolerance for the solver, if not specified uses the model default
**kwargs (dict) – additional parameters to be passed to the LoopStructural.modelling.features.builders.StructuralFrameBuilder and LoopStructural.modelling.features.builders.StructuralFrameBuilder.setup()

Returns:

fold_frame (FoldFrame) – created fold frame

Notes

This function build a structural frame where the first coordinate is constrained with a fold interpolator. Keyword arguments can be included to constrain

LoopStructural.GeologicalModel.get_interpolator()
LoopStructural.StructuralFrameBuilder
LoopStructural.StructuralFrameBuilder.setup()

Building a folded foliation uses the fold interpolation code from Laurent et al., 2016

and fold profile fitting from Grose et al., 2017. For more information about the fold modelling see LoopStructural.modelling.features.fold.FoldEvent, LoopStructural.modelling.features.builders.FoldedFeatureBuilder

create_and_add_folded_foliation(foliation_name, *, foliation_data=None, interpolatortype='DFI', nelements=10000, buffer=0.1, fold_frame=None, svario=True, tol=None, invert_fold_norm=False, **kwargs)#

Create a folded foliation field from data and a fold frame

Parameters:

foliation_data (str) – unique string in type column of data frame
fold_frame (FoldFrame)
svario (Boolean) – whether to calculate svariograms, saves time if avoided
kwargs – additional kwargs to be passed through to other functions

Returns:

feature (GeologicalFeature) – created geological feature

Notes

Building a folded foliation uses the fold interpolation code from Laurent et al., 2016

and fold profile fitting from Grose et al., 2017. For more information about the fold modelling see LoopStructural.modelling.features.fold.FoldEvent, LoopStructural.modelling.features.builders.FoldedFeatureBuilder

create_and_add_foliation(series_surface_name: str, *, series_surface_data: DataFrame = None, interpolatortype: str = 'FDI', nelements: int = 1000, tol=None, faults=None, **kwargs)#

Parameters:

series_surface_name (string) – corresponding to the feature_name in the data
series_surface_data (pd.DataFrame, optional) – data frame containing the surface data
interpolatortype (str) – the type of interpolator to use, default is ‘FDI’
nelements (int) – the number of elements to use in the series surface
tol (float, optional) – tolerance for the solver, if not specified uses the model default
faults (list, optional) – list of faults to be used in the series surface, if not specified uses the model faults
kwargs

Returns:

feature (GeologicalFeature) – the created geological feature

Notes

This function creates an instance of a LoopStructural.modelling.features.builders.GeologicalFeatureBuilder and will return a LoopStructural.modelling.features.builders.GeologicalFeature The feature is not interpolated until either LoopStructural.modelling.features.builders.GeologicalFeature.evaluate_value() is called or LoopStructural.modelling.core.GeologicalModel.update()

An interpolator will be chosen by calling LoopStructural.GeologicalModel.get_interpolator()

create_and_add_intrusion(intrusion_name, intrusion_frame_name, *, intrusion_frame_parameters={}, intrusion_lateral_extent_model=None, intrusion_vertical_extent_model=None, geometric_scaling_parameters={}, **kwargs)#

Note

An intrusion in built in two main steps: (1) Intrusion builder: intrusion builder creates the intrusion structural frame.

This object is curvilinear coordinate system of the intrusion constrained with intrusion network points, and flow and inflation measurements (provided by the user). The intrusion network is a representation of the approximated location of roof or floor contact of the intrusion. This object might be constrained using the anisotropies of the host rock if the roof (or floor) contact is not well constrained.

Intrusion feature: simulation of lateral and vertical extent of intrusion within the model volume. The simulations outcome consist in thresholds distances along the structural frame coordinates that are used to constrained the extent of the intrusion.

Parameters:

intrusion_name (string,) – name of intrusion feature in model data
intrusion_frame_name (string,) – name of intrusion frame in model data
function (intrusion_lateral_extent_model =) – geometrical conceptual model for simulation of lateral extent

:param : geometrical conceptual model for simulation of lateral extent :param intrusion_vertical_extent_model = function: geometrical conceptual model for simulation of vertical extent :param : geometrical conceptual model for simulation of vertical extent :param intrusion_frame_parameters = dictionary: :param kwargs:

Returns:: intrusion feature

data_for_feature(feature_name: str) → DataFrame#

Get all of the data associated with a geological feature

Parameters:: feature_name (str) – the unique identifying name of the feature
Returns:: pd.DataFrame – data frame containing all of the data in the model associated with this feature

evaluate_fault_displacements(points, scale=True)#

Evaluate the fault displacement magnitude at each location

Parameters:

xyz (np.array((N,3),dtype=float)) – locations
scale (bool) – whether to rescale the xyz before evaluating model

Returns:

fault_displacement (np.array(N,dtype=float)) – the fault displacement magnitude

evaluate_feature_gradient(feature_name, xyz, scale=True)#

Evaluate the gradient of the geological feature at a location

Parameters:

feature_name (string) – name of the geological feature
xyz (np.array((N,3))) – locations to evaluate
scale (bool, optional) – whether to scale real world points into model scale, by default True

Returns:

results (np.array((N,3))) – gradient of the scalar field at the locations specified

evaluate_feature_value(feature_name, xyz, scale=True)#

Evaluate the scalar value of the geological feature given the name at locations xyz

Parameters:

feature_name (string) – name of the feature
xyz (np.array((N,3))) – locations to evaluate
scale (bool, optional) – whether to scale real world points into model scale, by default True

Returns:

np.array((N)) – vector of scalar values

Examples

Evaluate on a voxet using model boundaries

>>> x = np.linspace(model.bounding_box[0, 0], model.bounding_box[1, 0],
                nsteps[0])
>>> y = np.linspace(model.bounding_box[0, 1], model.bounding_box[1, 1],
                nsteps[1])
>>> z = np.linspace(model.bounding_box[1, 2], model.bounding_box[0, 2],
                nsteps[2])
>>> xx, yy, zz = np.meshgrid(x, y, z, indexing='ij')
>>> xyz = np.array([xx.flatten(), yy.flatten(), zz.flatten()]).T
>>> model.evaluate_feature_vaue('feature',xyz,scale=False)

Evaluate on points in UTM coordinates

>>> model.evaluate_feature_vaue('feature',utm_xyz)

evaluate_model(xyz: ndarray, *, scale: bool = True) → ndarray#

Evaluate the stratigraphic id at each location

Parameters:

xyz (np.array((N,3),dtype=float)) – locations
scale (bool) – whether to rescale the xyz before evaluating model

Returns:

stratigraphic_id (np.array(N,dtype=int)) – the stratigraphic index for locations

Examples

Evaluate on a voxet

>>> x = np.linspace(model.bounding_box[0, 0], model.bounding_box[1, 0],
                nsteps[0])
>>> y = np.linspace(model.bounding_box[0, 1], model.bounding_box[1, 1],
                nsteps[1])
>>> z = np.linspace(model.bounding_box[1, 2], model.bounding_box[0, 2],
                nsteps[2])
>>> xx, yy, zz = np.meshgrid(x, y, z, indexing='ij')
>>> xyz = np.array([xx.flatten(), yy.flatten(), zz.flatten()]).T
>>> model.evaluate_model(xyz,scale=False)

Evaluate on points defined by regular grid function

>>> model.evaluate_model(model.regular_grid(shuffle=False),scale=False)

Evaluate on a map

>>> x = np.linspace(self.bounding_box[0, 0], self.bounding_box[1, 0],
                nsteps[0])
>>> y = np.linspace(self.bounding_box[0, 1], self.bounding_box[1, 1],
                nsteps[1])
>>> xx, yy = np.meshgrid(x, y, indexing='ij')
>>> zz = np.zeros_like(yy)
>>> xyz = np.array([xx.flatten(), yy.flatten(), zz.flatten()]).T
>>> model.evaluate_model(model.regular_grid(shuffle=False),scale=False)

Evaluate on points in reference coordinate system >>> model.evaluate_model(xyz,scale=True)

evaluate_model_gradient(points: ndarray, *, scale: bool = True) → ndarray#

Evaluate the gradient of the stratigraphic column at each location

Parameters:

points (np.ndarray) – location to evaluate
scale (bool, optional) – whether to scale the points into model domain, by default True

Returns:

np.ndarray – N,3 array of gradient vectors

fault_names()#

Get name of all faults in the model

Returns:: list – list of the names of the faults in the model

property faults#

Get all of the fault features in the model

Returns:: list – a list of LoopStructural.modelling.features.FaultSegment

classmethod from_file(file)#

Load a geological model from file

Parameters:: file (string) – path to the file
Returns:: GeologicalModel – the geological model object

classmethod from_processor(processor)#

Builds a model from a LoopStructural.modelling.input.ProcessInputData object This object stores the observations and order of the geological features

Parameters:: processor (ProcessInputData) – any type of ProcessInputData
Returns:: GeologicalModel – a model with all of the features, need to call model.update() to run interpolation

get_feature_by_name(feature_name) → GeologicalFeature#

Returns a feature from the mode given a name

Parameters:: feature_name (string) – the name of the feature
Returns:: feature (GeologicalFeature) – the geological feature with the specified name, or none if no feature

regular_grid(*, nsteps=None, shuffle=True, rescale=False, order='C')#

Return a regular grid within the model bounding box

Parameters:: nsteps (tuple) – number of cells in x,y,z
Returns:: xyz (np.array((N,3),dtype=float)) – locations of points in regular grid

rescale(points: ndarray, *, inplace: bool = False) → ndarray#

Convert from model scale to real world scale - in the future this should also do transformations?

Parameters:

points (np.array((N,3),dtype=double))
inplace (boolean) – whether to return a modified copy or modify the original array

Returns:

points (np.array((N,3),dtype=double))

scale(points: ndarray, *, inplace: bool = False) → ndarray#

Take points in UTM coordinates and reproject into scaled model space

Parameters:

points (np.array((N,3),dtype=float)) – points to
inplace (bool, optional default = True) – whether to copy the points array or update the passed array

Returns:

points (np.a::rray((N,3),dtype=double))

set_stratigraphic_column(stratigraphic_column, cmap='tab20')#

Adds a stratigraphic column to the model

Parameters:

stratigraphic_column (dictionary)
cmap (matplotlib.cmap)

Notes

stratigraphic_column is a nested dictionary with the format {‘group’:

{‘series1’:
{‘min’:0., ‘max’:10.,’id’:0,’colour’:}

}

}

property stratigraphic_column#

Get the stratigraphic column of the model

Returns:: StratigraphicColumn – the stratigraphic column of the model

stratigraphic_ids()#

Return a list of all stratigraphic ids in the model

Returns:: ids (list) – list of unique stratigraphic ids, featurename, unit name and min and max scalar values

to_dict()#

Convert the geological model to a json string

Returns:: json (str) – json string of the geological model

to_file(file)#

Save a model to a pickle file requires dill

Parameters:: file (string) – path to file location

LoopStructural.GeologicalModel#

This Page