layermesh.mesh module¶

Layered computational meshes.

class layermesh.mesh.cell(lay, col, index=None)¶

Bases: object

Mesh cell. On creation, the layer and column defining the cell (and optionally the cell index) are specified.

property above¶: Cell above the current cell, or None if there is no cell above it.

property below¶: Cell below the current cell, or None if there is no cell below it.

property centre¶: Centroid of cell.

property centroid¶: Centroid of cell.

column¶: Cell column object.

find(match, indices=False)¶

Returns cell, column or layer satisfying the criterion match.

The match parameter can be:

a function taking a cell and returning a Boolean: the cell is returned if it matches, otherwise None
a scalar: match is interpreted as an elevation and the cell layer is returned if the elevation is inside it
a 2-D point (tuple, list or array of length 2): match is interpreted as a horizontal position, and the cell column is returned if the position is inside it
a polygon (tuple, list or array of 2-D points): the cell column is returned if the cell column centroid is inside the polygon
a 3-D point (tuple, list or array of length 3): the cell is returned if the point is inside it

If indices is True, the cell, column or layer index is returned rather than the cell, column or layer itself.

In each case, None is returned if there is no match.

index¶: Index of the cell in the mesh.

layer¶: Cell layer object.

property neighbour¶: Set of neighbouring cells in the mesh, i.e. those that share a common face.

property num_neighbours¶: Number of neighbouring cells in the mesh, i.e. those that share a common face.

property num_nodes¶: Number of nodes in the cell (at both top and bottom of layer).

property surface¶: True if the cell is at the surface of the mesh, False otherwise.

property volume¶: Volume of cell.

class layermesh.mesh.column(node, index=None)¶

Bases: _layered_object

Mesh column. On creation, the column’s nodes (and optionally index) are specified.

property angle_ratio¶

Angle ratio, defined as the ratio of the largest interior angle to the smallest interior angle.

This can be used as a measure of the skewness of the column, with values near 1 being less skewed.

property area¶: Area of column.

property bounding_box¶: Horizontal bounding box of column.

cell¶: List of cells in the column.

property centre¶: Column centroid.

property centroid¶: Column centroid.

property face_length¶: Array of lengths of the column faces.

property face_length_ratio¶: Face length ratio, defined as the ratio of the longest face length to the shortest face length (a generalisation of the aspect ratio for quadrilateral columns).

find(match, indices=False, sort=False)¶

Returns cells, columns or layers satisfying the criterion match.

The match parameter can be:

a function taking a cell and returning a Boolean: a list of matching cells is returned
a scalar: match is interpreted as an elevation, and the layer containing it is returned
a 2-D point (tuple, list or array of length 2): match is interpreted as a horizontal position, and self is returned if it contains the point
a polygon (tuple, list or array of 2-D points): self is returned if its centroid is inside the polygon
a 3-D point (tuple, list or array of length 3): match is interpreted as a 3-D position, and the cell containing it is returned

If indices is True, the cell, column or layer indices are returned rather than the cells, columns or layers themselves.

If sort is True, then lists of results are sorted by index.

If no match is found, then None is returned, except when the expected result is a list, in which case an empty list is returned.

index¶: Integer containing the column’s index in the mesh.

property interior_angle¶: Array of interior angles for each node in the column.

layer¶: List of layers in the column.

neighbour¶: Set containing the neighbouring columns (those that share a face).

node¶: List of the node objects in the column.

property num_cells¶: Number of cells in the column.

property num_layers¶: Number of layers in the column.

property num_neighbours¶: Number of neighbouring columns (those that share a face).

property num_nodes¶: Number of nodes in the column.

property polygon¶: Polygon (list of arrays of length 2) formed by column node positions.

set_layers(layers, num_layers)¶: Sets column layers to be the last num_layers layers from the specified list.

set_surface(layers, surface=None)¶

Sets column layers from the given list, according to the specified surface elevation.

If surface = None, then the column is assigned all layers in the list. Otherwise, it is assigned all layers with centres below the specified surface elevation.

property side_neighbour¶: List of neighbouring columns corresponding to each column side (or None if the column side is on a boundary).

property surface¶: Surface elevation of the column, given by the top elevation of its uppermost layer. (This property is read-only: use set_surface() or set_layers() to set the layers in the column.)

translate(shift)¶: Translates column horizontally by the specified shift array (a tuple, list or array of length 2).

property volume¶: Column volume.

class layermesh.mesh.column_face(column)¶

Bases: object

Face between two columns. On creation, the two columns on either side of the face are specified.

property angle_cosine¶

Cosine of angle between the face and the line joining the column centroids on either side.

This can be used to measure the orthogonality of the face: orthogonal faces have angle cosine zero.

column¶: List or tuple of column objects on either side of the face.

node¶: List of node objects at either end of the face.

class layermesh.mesh.layer(bottom, top, index=None)¶

Bases: object

Mesh layer. On creation, the bottom and top elevations of the layer (and optionally the layer index) are specified.

above¶: Layer above this one, if it exists, otherwise None.

property area¶: Horizontal area of layer.

below¶: Layer below this one, if it exists, otherwise None.

bottom¶: Bottom elevation of the layer.

cell¶: List of cells in the layer.

property centre¶: Elevation of layer centre.

column¶: List of columns in the layer.

column_cell¶: Dictionary of cells, keyed by column indices.

find(match, indices=False, sort=False)¶

Returns cells, columns or layer satifying the criterion match.

The match parameter can be:

a function taking a cell and returning a Boolean: a list of matching cells is returned
a scalar: match is interpreted as an elevation, and the layer is returned if the elevation is inside it
a 2-D point (tuple, list or array of length 2): match is interpreted as a horizontal position, and the column containing it is returned
a polygon (tuple, list or array of 2-D points): a list of columns inside the polygon are returned
a 3-D point (tuple, list or array of length 3): match is interpreted as a 3-D position, and the cell containing it is returned

If indices is True, the cell, column or layer indices are returned rather than the cells, columns or layer themselves.

If sort is True, then lists of results are sorted by index.

If no match is found, then None is returned, except when the expected result is a list, in which case an empty list is returned.

property horizontal_bounds¶: Horizontal bounding box for layer (list of two arrays of length 2, representing the bottom left and top right corner coordinates of the bounding box).

index¶: Layer index in the mesh (numbered from top down).

property node¶: Set of nodes in the layer.

property num_cells¶: Number of cells in the layer.

property num_columns¶: Number of columns in the layer.

property quadtree¶: Quadtree object for column searching within the layer.

property thickness¶: Vertical thickness of layer.

top¶: Top elevation of the layer.

translate(shift)¶: Translates layer by specified 3-D shift (a tuple, list or array of length 3).

property volume¶: Volume of layer.

class layermesh.mesh.mesh(filename=None, **kwargs)¶

Bases: _layered_object

A mesh can be created either by reading it from a file, or via other parameters.

If filename is specified, the mesh is read from the given HDF5 file.

Otherwise, a rectangular mesh can be created using the rectangular parameter. Mesh spacings in the three coordinate directions are specified via tuples, lists or arrays of spacings. The rectangular parameter is itself a tuple or list of three of these mesh spacing specifications.

The surface elevations can be specified using the surface parameter. This can be either a dictionary of pairs of column indices and corresponding surface elevations, or a tuple, list or array of surface elevations for all columns. If None is specified (the default) then all column surfaces will be set to the top of the uppermost layer.

By default, mesh cells are ordered first by cell type (number of nodes, in decreasing order), then layer and finally by column within each layer, from the top to bottom of the mesh. The sorting of cell types can be reversed or disabled by setting the cell_type_sort parameter: a value of 1 sorts cells in increasing type order, and a value of zero disables cell type sorting.

add_column(col)¶: Adds a column to the mesh.

add_layer(lay)¶: Adds a layer to the mesh.

add_node(n)¶: Adds a horizontal node to the mesh.

property area¶: Horizontal area of the mesh.

property boundary_nodes¶: Set of nodes on the boundary of the mesh.

property bounds¶: Horizontal bounding box for the mesh.

cell¶: List of cell objects in the mesh.

cell_type_sort¶: Integer controlling sorting of cells by type. A value of -1 (the default) gives cells sorted by decreasing type (number of nodes). A value of 1 gives cells sorted by increasing type, while a value of zero disables cell type sorting.

property centre¶: Horizontal centre of the mesh (an array of length 2), approximated by an area-weighted average of column centres.

column¶: List of column objects in the mesh.

column_faces(columns=None)¶: Returns a list of the column faces between the specified columns. A list of the columns may be optionally specified, otherwise all columns will be included.

column_in_layer(col, lay)¶: Returns True if column is in the specified layer, or False otherwise.

column_track(line)¶: Returns a list of tuples of (column,entrypoint,exitpoint) representing the horizontal track traversed by the specified line through the grid. Line is a tuple of two 2D arrays. The resulting list is ordered by distance from the start of the line.

delete_column(col)¶: Deletes the specified column object from the mesh.

export(filename, fmt=None)¶: Exports 3-D mesh using meshio, to file with the specified name. If the format is not specified via the fmt parameter, it is determined from the filename extension.

find(match, indices=False, sort=False)¶

Returns cells, columns or layers satisfying the criterion match.

The match parameter can be:

a function taking a cell and returning a Boolean: a list of matching cells is returned
a scalar: match is interpreted as an elevation, and the layer containing it is returned
a 2-D point (tuple, list or array of length 2): match is interpreted as a horizontal position, and the mesh column containing it is returned
a polygon (tuple, list or array of 2-D points): a list of mesh columns inside the polygon are returned
a 3-D point (tuple, list or array of length 3): match is interpreted as a 3-D position, and the mesh cell containing it is returned

If indices is True, the cell, column or layer indices are returned rather than the cells, columns or layers themselves.

If sort is True, then lists of results are sorted by index.

If no match is found, then None is returned, except when the expected result is a list, in which case an empty list is returned.

fit_data_to_columns(data, columns=None, smoothing=0.01)¶

Fits scattered data to the columns of the mesh, using smoothed piecewise constant least-squares fitting.

The data should be in the form of a 3-column array with x,y,z data in each row. Fitting can be carried out over a subset of the mesh columns by specifying a tuple or list of columns.

Increasing the smoothing parameter will decrease gradients between columns, and a non-zero value must be used to obtain a solution if any columns contain no data.

fit_surface(data, columns=None, smoothing=0.01)¶

Fits surface elevation data to determine the number of layers in each column.

The data should be in the form of a 3-column array with x,y,z data in each row. Fitting can be carried out over a subset of the mesh columns by specifying a tuple or list of columns.

Increasing the smoothing parameter will decrease gradients between columns, and a non-zero value must be used to obtain a solution if any columns contain no data.

identify_column_neighbours()¶: Identifies neighbours for each column.

layer¶: List of layer objects in the mesh.

layer_plot(lay=-1, **kwargs)¶

Creates a 2-D Matplotlib plot of the mesh at a specified layer. The lay parameter can be either a layer object or a layer index.

Other optional parameters:

aspect: the aspect ratio of the axes (default ‘equal’).
axes: a Matplotlib axes object on which to draw the plot. If not specified, then a new axes object will be created internally.
colourmap: a Matplotlib colourmap object for shading the plot according to the value array (default None).
elevation: used to specify an elevation instead of a layer.
label: a string (or None, the default) specifying what labels are to be drawn at the centre of each column. Possible values are ‘column’ (to label with column indices), ‘cell’ (to label cell indices) or ‘value’ (to label with the value array).
label_format: format string for the labels (default ‘%g’).
label_colour: the colour of the labels (default ‘black’).
linecolour: the colour of the mesh grid (default ‘black’).
linewidth: the line width of the mesh (default 0.2).
value: a tuple, list or array of values to plot over the mesh, of length equal to the number of cells in the mesh.
xlabel: label string for the plot x-axis (default ‘x’).
ylabel: label string for the plot y-axis (default ‘y’).

property meshio_points_cells¶: Lists of 3-D points and cells suitable for mesh input/output using meshio library.

node¶: List of node objects in the mesh.

nodes_in_columns(columns)¶: Returns a set of nodes in the specified columns.

property num_cells¶: Number of 3-D cells in the mesh.

property num_columns¶: Number of columns in the mesh.

property num_layers¶: Number of layers in the mesh.

property num_nodes¶: Number of 2-D nodes in the mesh.

optimize(nodes=None, columns=None, weight={'orthogonal': 1})¶

Adjusts horizontal positions of specified nodes to optimize the mesh. If no nodes are specified, all node positions are optimized. If columns are specified, the positions of nodes in those columns are optimized.

Three types of optimization are offered, with their relative importance in the optimization specified via the weight dictionary parameter. This can contain up to three keys:

‘orthogonal’: the orthogonality of the mesh faces
‘skewness’: the skewness of the columns
‘aspect’: the aspect ratio of the columns

Omitting any of these keys from the weight parameter will give them zero weight. Weights need not sum to 1: only their relative magnitudes matter.

The optimization is carried out by using the leastsq() function from the scipy.optimize module to minimize an objective function formed from a weighted combination of the mesh quality measures above.

read(filename)¶: Reads mesh from HDF5 file.

refine(columns=None)¶

Refines selected columns in the mesh. If no columns are specified, then all columns are refined. The columns parameter can be a set, tuple or list of column objects.

Each selected column is divided into four new columns. Triangular transition columns are added around the edge of the refinement area as needed.

Note that the selected columns must be either triangular or quadrilateral (columns with more than four edges cannot be refined).

Mesh refinement will generally alter the indexing of the mesh nodes, columns and cells, even those not within the refinement area. Hence, it should not be assumed, for example, that columns outside the refinement area will retain their original indices after the refinement.

Based on the mulgrid refine() method in PyTOUGH.

rotate(angle, centre=None)¶: Rotates the mesh horizontally by the specified angle (degrees clockwise). If no centre is specified, the mesh is rotated about its own centre.

set_column_layers(num_layers)¶: Sets column layers from dictionary (keyed by column indices) or list/array of layer counts for each column.

set_layer_columns(lay)¶: Populates the list of columns for a given layer.

set_layers(elevations)¶: Sets mesh layers according to specified vertical layer boundary elevations, from the top down.

set_rectangular_columns(spacings)¶: Sets rectangular mesh columns according to specified lists of horizontal mesh spacings.

set_surface(surface)¶: Sets column layers from surface dictionary (keyed by column indices) or list/array of values for all columns.

setup(indices=False)¶: Sets up internal mesh variables, including node, column and layer indices if needed.

setup_cells()¶: Sets up cell properties of mesh, layers and columns.

slice_plot(line='x', **kwargs)¶

Creates a 2-D Matplotlib plot of the mesh through a specified vertical slice. The horizontal line defining the slice can be either:

‘x’: to plot through the mesh centre along the x-axis
‘y’: to plot through the mesh centre along the y-axis
a number representing an angle (in degrees), clockwise from the y-axis, to plot through the centre of the mesh at that angle
a tuple, list or array of two end-points for the line, each point being itself a tuple, list or array of length 2

Other optional parameters:

aspect: the aspect ratio of the axes (default ‘auto’).
axes: a Matplotlib axes object on which to draw the plot. If not specified, then a new axes object will be created internally.
colourmap: a Matplotlib colourmap object for shading the plot according to the value array (default None).
label: a string (or None, the default) specifying what labels are to be drawn at the centre of each cell. Possible values are ‘cell’ (to label cell indices) or ‘value’ (to label with the value array).
label_format: format string for the labels (default ‘%g’).
label_colour: the colour of the labels (default ‘black’).
linecolour: the colour of the mesh grid (default ‘black’).
linewidth: the line width of the mesh (default 0.2).
value: a tuple, list or array of values to plot over the mesh, of length equal to the number of cells in the mesh.
xlabel: label string for the plot x-axis (default ‘x’).
ylabel: label string for the plot y-axis (default ‘z’).

property surface¶: Array of column surface elevations.

property surface_cells¶: List of cells at the surface of the mesh.

translate(shift)¶: Translates the mesh by the specified 3-D shift vector (tuple, list or array of length 3).

type_columns(num_nodes)¶: Returns a list of mesh columns of a specified type, i.e. number of nodes.

property volume¶: Total volume of the mesh.

write(filename)¶: Writes mesh to HDF5 file.

class layermesh.mesh.node(pos, index=None)¶

Bases: object

2-D mesh node. On creation, the node’s horizontal position (and optionally index) are specified.

column¶: Set containing the column objects the node belongs to.

find(polygon, indices=False)¶: Returns self if the node is inside the specified polygon (tuple, list or array of 2-D points, each one a tuple, list or array of length 2), otherwise None.

index¶: Integer containing the node’s index in the mesh.

pos¶: Array containing the node’s horizontal position.