LoopStructural.modelling.GeologicalModel#

class LoopStructural.modelling.GeologicalModel(origin: ndarray, maximum: ndarray, data=None, nsteps=(50, 50, 25), reuse_supports=False, logfile=None, loglevel='info')#

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

scale_factor#

the scale factor used to rescale the model

Type:

double

Parameters:

  • origin (numpy array) – specifying the origin of the model

  • maximum (numpy array) – specifying the maximum extent of the model

  • rescale (bool) – whether to rescale the model to between 0/1

  • epsion (float) – a fudge factor for isosurfacing, used to make sure surfaces appear

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__(origin: ndarray, maximum: ndarray, data=None, nsteps=(50, 50, 25), reuse_supports=False, logfile=None, loglevel='info')#
Parameters:

  • origin (numpy array) – specifying the origin of the model

  • maximum (numpy array) – specifying the maximum extent of the model

  • rescale (bool) – whether to rescale the model to between 0/1

  • epsion (float) – a fudge factor for isosurfacing, used to make sure surfaces appear

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__(origin, maximum[, data, nsteps, ...])

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.

check_inialisation()

create_and_add_domain_fault(fault_surface_data)

create_and_add_fault(fault_surface_data, ...)

create_and_add_fold_frame(foldframe_data[, ...])

create_and_add_folded_fold_frame(fold_frame_data)

create_and_add_folded_foliation(foliation_data)

Create a folded foliation field from data and a fold frame

create_and_add_foliation(series_surface_data)

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_map2loop_directory(m2l_directory[, ...])

Alternate constructor for a geological model using m2l output

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])

regular_grid([nsteps, shuffle, rescale, order])

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

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_surface_data, displacement, 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, **kwargs)#
Parameters:

  • fault_surface_data (string) – name of the fault surface data in the dataframe

  • displacement (displacement magnitude)

  • 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(foldframe_data, interpolatortype='FDI', nelements=1000, tol=None, buffer=0.1, **kwargs)#
Parameters:

  • foldframe_data (string) – unique string in feature_name column

  • kwargs

Returns:

fold_frame (FoldFrame) – the created fold frame

create_and_add_folded_fold_frame(fold_frame_data, interpolatortype='FDI', nelements=10000, fold_frame=None, tol=None, **kwargs)#
Parameters:

  • fold_frame_data (string) – name of the feature to be added

  • fold_frame (StructuralFrame, optional) – the fold frame for the fold if not specified uses last feature added

  • kwargs (dict) – parameters passed to child functions

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_data, 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_data: str, interpolatortype: str = 'FDI', nelements: int = 1000, tol=None, faults=None, **kwargs)#
Parameters:

  • series_surface_data (string) – corresponding to the feature_name in the data

  • 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.

  1. 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_map2loop_directory(m2l_directory, foliation_params={}, fault_params={}, use_thickness=True, vector_scale=1, gradient=False, **kwargs)#

Alternate constructor for a geological model using m2l output

Uses the information saved in the map2loop files to build a geological model. You can specify kwargs for building foliation using foliation_params and for faults using fault_params. faults is a flag that allows for the faults to be skipped.

Parameters:

m2l_directory (string) – path to map2loop directory

Returns:

(GeologicalModel, dict) – the created geological model and a dictionary of the map2loop data

Notes

For additional information see LoopStructural.modelling.input.Map2LoopProcessor and LoopStructural.GeologicalModel.from_processor()

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’:}

}

}

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