discretize.TreeMesh

class discretize.TreeMesh(h=None, origin=None, diagonal_balance=None, **kwargs)

Class for QuadTree (2D) and OcTree (3D) meshes.

Tree meshes are numerical grids where the dimensions of each cell are powers of 2 larger than some base cell dimension. Unlike the TensorMesh class, gridded locations and numerical operators for instances of TreeMesh cannot be simply constructed using tensor products. Furthermore, each cell is an instance of TreeCell .

Each cell of a TreeMesh has a certain level associated with it which describes its height in the structure of the tree. The tree mesh is refined by specifying what level you want in a given location. They start at level 0, defining the largest possible cell on the mesh, and go to a level of max_level describing the finest possible cell on the mesh. TreeMesh` contains several refinement functions used to design the mesh, starting with a general purpose refinement function, along with several faster specialized refinement functions based on fundamental geometric entities:

• refine -> The general purpose refinement function supporting arbitrary defined functions

• insert_cells

• refine_ball

• refine_line

• refine_triangle

• refine_box

• refine_tetrahedron

• refine_vertical_trianglular_prism

• refine_bounding_box

• refine_points

• refine_surface

Like array indexing in python, you can also supply negative indices as a level arguments to these functions to index levels in a reveresed order (i.e. -1 is equivalent to max_level).

Parameters:

h(dim) iterable of int, numpy.ndarray, or tuple

Defines the cell widths of the underlying tensor mesh along each axis. The length of the iterable object is equal to the dimension of the mesh (2 or 3). For a 3D mesh, the list would have the form [hx, hy, hz]. The number of cells along each axis must be a power of 2 .

Along each axis, the user has 3 choices for defining the cells widths for the underlying tensor mesh:

• int -> A unit interval is equally discretized into N cells.

• numpy.ndarray -> The widths are explicity given for each cell

• the widths are defined as a list of tuple of the form (dh, nc, [npad]) where dh is the cell width, nc is the number of cells, and npad (optional) is a padding factor denoting exponential increase/decrease in the cell width for each cell; e.g. [(2., 10, -1.3), (2., 50), (2., 10, 1.3)]

origin(dim) iterable, default: 0

Define the origin or ‘anchor point’ of the mesh; i.e. the bottom-left-frontmost corner. By default, the mesh is anchored such that its origin is at [0, 0, 0].

For each dimension (x, y or z), The user may set the origin 2 ways:

• a scalar which explicitly defines origin along that dimension.

• {‘0’, ‘C’, ‘N’} a str specifying whether the zero coordinate along each axis is the first node location (‘0’), in the center (‘C’) or the last node location (‘N’) (see Examples).

diagonal_balancebool, optional

Whether to balance cells along the diagonal of the tree during construction. This will affect all calls to refine the tree.

Attributes

area	area has been deprecated.
areaFx	areaFx has been deprecated.
areaFy	areaFy has been deprecated.
areaFz	areaFz has been deprecated.
average_cell_to_edge	Averaging operator from cell centers to edges (scalar quantities).
average_cell_to_face	Averaging operator from cell centers to faces (scalar quantities).
average_cell_to_face_x	Averaging operator from cell centers to x faces (scalar quantities).
average_cell_to_face_y	Averaging operator from cell centers to y faces (scalar quantities).
average_cell_to_face_z	Averaging operator from cell centers to z faces (scalar quantities).
average_cell_vector_to_face	Averaging operator from cell centers to faces (vector quantities).
average_edge_to_cell	Averaging operator from edges to cell centers (scalar quantities).
average_edge_to_cell_vector	Averaging operator from edges to cell centers (vector quantities).
average_edge_to_face	Averaging operator from edges to faces.
average_edge_x_to_cell	Averaging operator from x-edges to cell centers (scalar quantities).
average_edge_y_to_cell	Averaging operator from y-edges to cell centers (scalar quantities).
average_edge_z_to_cell	Averaging operator from z-edges to cell centers (scalar quantities).
average_face_to_cell	Averaging operator from faces to cell centers (scalar quantities).
average_face_to_cell_vector	Averaging operator from faces to cell centers (vector quantities).
average_face_x_to_cell	Averaging operator from x-faces to cell centers (scalar quantities).
average_face_y_to_cell	Averaging operator from y-faces to cell centers (scalar quantities).
average_face_z_to_cell	Averaging operator from z-faces to cell centers (scalar quantities).
average_node_to_cell	Averaging operator from nodes to cell centers (scalar quantities).
average_node_to_edge	Averaging operator from nodes to edges (scalar quantities).
average_node_to_edge_x	Averaging operator from nodes to x edges (scalar quantities).
average_node_to_edge_y	Averaging operator from nodes to y edges (scalar quantities).
average_node_to_edge_z	Averaging operator from nodes to z edges (scalar quantities).
average_node_to_face	Averaging operator from nodes to faces (scalar quantities).
average_node_to_face_x	Averaging operator from nodes to x faces (scalar quantities).
average_node_to_face_y	Averaging operator from nodes to y faces (scalar quantities).
average_node_to_face_z	Averaging operator from nodes to z faces (scalar quantities).
axis_u	Orientation of the first axis.
axis_v	Orientation of the second axis.
axis_w	Orientation of the third axis.
boundary_edge_vector_integral	Integrate a vector function on the boundary.
boundary_edges	Gridded boundary edge locations.
boundary_face_outward_normals	Outward normals of boundary faces.
boundary_face_scalar_integral	Represent the operation of integrating a scalar function on the boundary.
boundary_faces	Gridded boundary face locations.
boundary_node_vector_integral	Integrate a vector function dotted with the boundary normal.
boundary_nodes	Gridded boundary node locations.
cellBoundaryInd	cellBoundaryInd has been deprecated.
cellGrad	cellGrad has been deprecated.
cellGradBC	cellGradBC has been deprecated.
cellGradStencil	cellGradStencil has been deprecated.
cellGradx	cellGradx has been deprecated.
cellGrady	cellGrady has been deprecated.
cellGradz	cellGradz has been deprecated.
cell_boundary_indices	Returns the indices of the x, y (and z) boundary cells.
cell_centers	Gridded cell center locations.
cell_centers_x	Return x-coordinates of the cell centers along the x-direction.
cell_centers_y	Return y-coordinates of the cell centers along the y-direction.
cell_centers_z	Return z-coordinates of the cell centers along the z-direction.
cell_gradient	Cell gradient operator (cell centers to faces).
cell_gradient_BC	Boundary conditions matrix for the cell gradient operator (Deprecated).
cell_gradient_x	X-derivative operator (cell centers to x-faces).
cell_gradient_y	Y-derivative operator (cell centers to y-faces).
cell_gradient_z	Z-derivative operator (cell centers to z-faces).
cell_nodes	The index of all nodes for each cell.
cell_state	The current state of the cells on the mesh.
cell_volumes	Return cell volumes.
dim	The dimension of the mesh (1, 2, or 3).
edge	edge has been deprecated.
edgeCurl	edgeCurl has been deprecated.
edgeEx	edgeEx has been deprecated.
edgeEy	edgeEy has been deprecated.
edgeEz	edgeEz has been deprecated.
edge_curl	Edge curl operator (edges to faces)
edge_lengths	Returns the lengths of all edges in the mesh.
edge_nodes	The index of nodes for every edge.
edge_tangents	Unit tangent vectors for all mesh edges.
edges	Gridded edge locations.
edges_x	Gridded locations of non-hanging x-edges.
edges_y	Gridded locations of non-hanging y-edges.
edges_z	Gridded locations of non-hanging z-edges.
faceBoundaryInd	faceBoundaryInd has been deprecated.
faceDiv	faceDiv has been deprecated.
faceDivx	faceDivx has been deprecated.
faceDivy	faceDivy has been deprecated.
faceDivz	faceDivz has been deprecated.
face_areas	Returns the areas of all cell faces.
face_boundary_indices	Returns the indices of the x, y (and z) boundary faces.
face_divergence	Face divergence operator (faces to cell-centres).
face_normals	Unit normal vectors for all mesh faces.
face_x_divergence	X-derivative operator (x-faces to cell-centres).
face_y_divergence	Y-derivative operator (y-faces to cell-centres).
face_z_divergence	Z-derivative operator (z-faces to cell-centres).
faces	Gridded face locations.
faces_x	Gridded locations of non-hanging x-faces.
faces_y	Gridded locations of non-hanging y-faces.
faces_z	Gridded locations of non-hanging z-faces.
fill	How 'filled' the tree mesh is compared to the underlying tensor mesh.
finalized	Whether tree mesh is finalized.
h	Cell widths along each axis direction.
h_gridded	Gridded cell dimensions.
hanging_edges_x	Gridded locations of hanging x-edges.
hanging_edges_y	Gridded locations of hanging y-edges.
hanging_edges_z	Gridded locations of hanging z-edges.
hanging_faces_x	Gridded locations of hanging x-faces.
hanging_faces_y	Gridded locations of hanging y-faces.
hanging_faces_z	Gridded locations of hanging z-faces.
hanging_nodes	Gridded hanging node locations.
hx	Width of cells in the x direction.
hy	Width of cells in the y direction.
hz	Width of cells in the z direction.
maxLevel	maxLevel has been deprecated.
max_level	Maximum allowable refinement level for the mesh.
max_used_level	Maximum refinement level used.
n_cells	Total number of cells in the mesh.
n_edges	Total number of edges in the mesh.
n_edges_per_direction	The number of edges in each direction.
n_edges_x	Number of x-edges in the mesh.
n_edges_y	Number of y-edges in the mesh.
n_edges_z	Number of z-edges in the mesh.
n_faces	Total number of faces in the mesh.
n_faces_per_direction	The number of faces in each axis direction.
n_faces_x	Number of x-faces in the mesh.
n_faces_y	Number of y-faces in the mesh.
n_faces_z	Number of z-faces in the mesh.
n_hanging_edges	Total number of hanging edges in all dimensions.
n_hanging_edges_x	Number of hanging x-edges in the mesh.
n_hanging_edges_y	Number of hanging y-edges in the mesh.
n_hanging_edges_z	Number of hanging z-edges in the mesh.
n_hanging_faces	Total number of hanging faces in the mesh.
n_hanging_faces_x	Number of hanging x-faces in the mesh.
n_hanging_faces_y	Number of hanging y-faces in the mesh.
n_hanging_faces_z	Number of hanging z-faces in the mesh.
n_hanging_nodes	Number of hanging nodes.
n_nodes	Total number of nodes in the mesh.
n_total_edges	Total number of hanging and non-hanging edges in all dimensions.
n_total_edges_x	Number of hanging and non-hanging x-edges in the mesh.
n_total_edges_y	Number of hanging and non-hanging y-edges in the mesh.
n_total_edges_z	Number of hanging and non-hanging z-edges in the mesh.
n_total_faces	Total number of hanging and non-hanging faces in the mesh.
n_total_faces_x	Number of hanging and non-hanging x-faces in the mesh.
n_total_faces_y	Number of hanging and non-hanging y-faces in the mesh.
n_total_faces_z	Number of hanging and non-hanging z-faces in the mesh.
n_total_nodes	Number of hanging and non-hanging nodes.
nodalGrad	nodalGrad has been deprecated.
nodalLaplacian	nodalLaplacian has been deprecated.
nodal_gradient	Nodal gradient operator (nodes to edges)
nodal_laplacian	Not implemented on the TreeMesh.
nodes	Gridded non-hanging nodes locations.
nodes_x	Return x-coordinates of the nodes along the x-direction.
nodes_y	Return y-coordinates of the nodes along the y-direction.
nodes_z	Return z-coordinates of the nodes along the z-direction.
normals	normals has been deprecated.
orientation	Rotation matrix defining mesh axes relative to Cartesian.
origin	Origin or 'anchor point' of the mesh.
permuteCC	permuteCC has been deprecated.
permuteE	permuteE has been deprecated.
permuteF	permuteF has been deprecated.
permute_cells	Permutation matrix re-ordering of cells sorted by x, then y, then z.
permute_edges	Permutation matrix re-ordering of edges sorted by x, then y, then z.
permute_faces	Permutation matrix re-ordering of faces sorted by x, then y, then z.
project_edge_to_boundary_edge	Projection matrix from all edges to boundary edges.
project_face_to_boundary_face	Projection matrix from all faces to boundary faces.
project_node_to_boundary_node	Projection matrix from all nodes to boundary nodes.
reference_is_rotated	Indicate whether mesh uses standard coordinate axes.
reference_system	Coordinate reference system.
rotation_matrix	Alias for orientation.
shape_cells	Number of cells in each coordinate direction.
stencil_cell_gradient	Stencil for cell gradient operator (cell centers to faces).
stencil_cell_gradient_x	Differencing operator along x-direction to total (including hanging) x faces.
stencil_cell_gradient_y	Differencing operator along y-direction to total (including hanging) y faces.
stencil_cell_gradient_z	Differencing operator along z-direction to total (including hanging) z faces.
tangents	tangents has been deprecated.
total_nodes	Gridded hanging and non-hanging nodes locations.
vectorCCx	vectorCCx has been deprecated.
vectorCCy	vectorCCy has been deprecated.
vectorCCz	vectorCCz has been deprecated.
vectorNx	vectorNx has been deprecated.
vectorNy	vectorNy has been deprecated.
vectorNz	vectorNz has been deprecated.
vntE	Vector number of total edges along each axis.
vntF	Vector number of total faces along each axis.
vol	vol has been deprecated.
x0	Alias for the origin.

cell_bounds

Methods

average_cell_to_total_face_x(self)	Average matrix for cell center to total (including hanging) x faces.
average_cell_to_total_face_y(self)	Average matrix for cell center to total (including hanging) y faces.
average_cell_to_total_face_z(self)	Average matrix for cell center to total (including hanging) z faces.
cell_gradient_weak_form_robin([alpha, beta, ...])	Create Robin conditions pieces for weak form of the cell gradient operator (cell centers to faces).
cell_levels_by_index(indices)	Fast function to return a list of levels for the given cell indices.
closest_points_index(locations[, grid_loc, ...])	Find the indicies for the nearest grid location for a set of points.
copy()	Make a copy of the current mesh.
deserialize(items, **kwargs)	Create this mesh from a dictionary of attributes.
edge_divergence_weak_form_robin([alpha, ...])	Create Robin conditions pieces for weak form of the edge divergence operator (edges to nodes).
equals(other)	Compare the current mesh with another mesh to determine if they are identical.
finalize(self)	Finalize the TreeMesh.
from_omf(element)	Convert an omf object to a discretize mesh.
getBCProjWF(*args, **kwargs)	getBCProjWF has been removed.
getBCProjWF_simple(*args, **kwargs)	getBCProjWF_simple has been removed.
getEdgeInnerProduct(*args, **kwargs)	getEdgeInnerProduct has been removed.
getEdgeInnerProductDeriv(*args, **kwargs)	getEdgeInnerProductDeriv has been removed.
getFaceInnerProduct(*args, **kwargs)	getFaceInnerProduct has been removed.
getFaceInnerProductDeriv(*args, **kwargs)	getFaceInnerProductDeriv has been removed.
getInterpolationMat(*args, **kwargs)	getInterpolationMat has been removed.
getTensor(*args, **kwargs)	getTensor has been removed.
get_BC_projections(BC[, discretization])	Create the weak form boundary condition projection matrices.
get_BC_projections_simple([discretization])	Create weak form boundary condition projection matrices for mixed boundary condition.
get_boundary_cells(self[, active_ind, direction])	Return the indices of boundary cells in a given direction given an active index array.
get_cells_along_line(self, x0, x1)	Find the cells in order along a line segment.
get_cells_in_aabb(self, x_min, ...)	Find the indices of cells that intersect an axis aligned bounding box (aabb)
get_cells_in_ball(self, center, double radius)	Find the indices of cells that intersect a ball
get_cells_in_tetrahedron(self, tetra)	Find the indices of cells that intersect a tetrahedron.
get_cells_in_triangle(self, triangle)	Find the indices of cells that intersect a triangle.
get_cells_in_vertical_trianglular_prism(...)	Find the indices of cells that intersect a vertical triangular prism.
get_cells_on_line(self, segment)	Find the cells intersecting a line segment.
get_cells_on_plane(self, origin, normal)	Find the indices of cells that intersect a plane.
get_containing_cells(self, points)	Return the cells containing the given points.
get_edge_inner_product([model, ...])	Generate the edge inner product matrix or its inverse.
get_edge_inner_product_deriv(model[, ...])	Get a function handle to multiply vector with derivative of edge inner product matrix (or its inverse).
get_edge_inner_product_line([model, ...])	Generate the edge inner product line matrix or its inverse.
get_edge_inner_product_line_deriv(model[, ...])	Get a function handle to multiply a vector with derivative of edge inner product line matrix (or its inverse).
get_edge_inner_product_surface([model, ...])	Generate the edge inner product surface matrix or its inverse.
get_edge_inner_product_surface_deriv(model)	Get a function handle to multiply a vector with derivative of edge inner product surface matrix (or its inverse).
get_face_inner_product([model, ...])	Generate the face inner product matrix or its inverse.
get_face_inner_product_deriv(model[, ...])	Get a function handle to multiply a vector with derivative of face inner product matrix (or its inverse).
get_face_inner_product_surface([model, ...])	Generate the face inner product matrix or its inverse.
get_face_inner_product_surface_deriv(model)	Get a function handle to multiply a vector with derivative of face inner product surface matrix (or its inverse).
get_interpolation_matrix(locs[, ...])	Construct a linear interpolation matrix from mesh.
get_overlapping_cells(self, rectangle)	Find the indicis of cells that overlap the given rectangle
get_tensor(key)	Return the base 1D arrays for a specified mesh tensor.
insert_cells(self, points, levels[, ...])	Insert cells into the TreeMesh that contain given points.
isInside(*args, **kwargs)	isInside has been removed.
is_inside(pts[, location_type])	Determine which points lie within the mesh.
number(self)	Number the cells, nodes, faces, and edges of the TreeMesh.
plotGrid(*args, **kwargs)	plotGrid has been deprecated.
plotImage(*args, **kwargs)	plotImage has been deprecated.
plotSlice(*args, **kwargs)	plotSlice has been deprecated.
plot_3d_slicer(v[, xslice, yslice, zslice, ...])	Plot slices of a 3D volume, interactively (scroll wheel).
plot_grid([ax, nodes, faces, centers, ...])	Plot the grid for nodal, cell-centered and staggered grids.
plot_image(v[, v_type, grid, view, ax, ...])	Plot quantities defined on a given mesh.
plot_slice(v[, v_type, normal, ind, ...])	Plot a slice of fields on the given 3D mesh.
point2index(locs)	Find cells that contain the given points.
projectEdgeVector(*args, **kwargs)	projectEdgeVector has been removed.
projectFaceVector(*args, **kwargs)	projectFaceVector has been removed.
project_edge_vector(edge_vectors)	Project vectors to the edges of the mesh.
project_face_vector(face_vectors)	Project vectors onto the faces of the mesh.
readModelUBC(*args, **kwargs)	readModelUBC has been removed.
readUBC(file_name[, directory])	Read 3D Tree mesh from UBC-GIF formatted file.
read_UBC(file_name[, directory])	Read 3D tree mesh (OcTree mesh) from UBC-GIF formatted file.
read_model_UBC(file_name[, directory])	Read UBC-GIF formatted file model file for 3D tree mesh (OcTree).
refine(self, function[, finalize, ...])	Refine TreeMesh with user-defined function.
refine_ball(self, points, radii, levels[, ...])	Refine TreeMesh using radial distance (ball) and refinement level for a cluster of points.
refine_bounding_box(points[, level, ...])	Refine within a bounding box based on the maximum and minimum extent of scattered points.
refine_box(self, x0s, x1s, levels[, ...])	Refine the TreeMesh within the axis aligned boxes to the desired level.
refine_line(self, path, levels[, finalize, ...])	Refine the TreeMesh along the line segment to the desired level.
refine_plane(self, origins, normals, levels)	Refine the TreeMesh along a plane to the desired level.
refine_points(points[, level, ...])	Refine the mesh at given points to the prescribed level.
refine_surface(xyz[, level, ...])	Refine along a surface triangulated from xyz to the prescribed level.
refine_tetrahedron(self, tetra, levels[, ...])	Refine the TreeMesh along the tetrahedron to the desired level.
refine_triangle(self, triangle, levels[, ...])	Refine the TreeMesh along the triangle to the desired level.
refine_vertical_trianglular_prism(self, ...)	Refine the TreeMesh along the trianglular prism to the desired level.
save([file_name, verbose])	Save the mesh to json.
serialize()	Represent the mesh's attributes as a dictionary.
setCellGradBC(*args, **kwargs)	setCellGradBC has been removed.
set_cell_gradient_BC(BC)	Set boundary conditions for derivative operators acting on cell-centered quantities.
toVTK([models])	Convert mesh (and models) to corresponding VTK or PyVista data object.
to_dict()	Represent the mesh's attributes as a dictionary.
to_omf([models])	Convert to an omf data object.
to_vtk([models])	Convert mesh (and models) to corresponding VTK or PyVista data object.
validate()	Return the validation state of the mesh.
writeModelUBC(*args, **kwargs)	writeModelUBC has been removed.
writeUBC(*args, **kwargs)	writeUBC has been removed.
writeVTK(file_name[, models, directory])	Convert mesh (and models) to corresponding VTK or PyVista data object then writes to file.
write_UBC(file_name[, models, directory])	Write OcTree mesh (and models) to UBC-GIF formatted files.
write_model_UBC(file_name, model[, directory])	Write 3D tree model (OcTree) to UBC-GIF formatted file.
write_vtk(file_name[, models, directory])	Convert mesh (and models) to corresponding VTK or PyVista data object then writes to file.

Examples

Here we generate a basic 2D tree mesh.

>>> from discretize import TreeMesh
>>> import numpy as np
>>> import matplotlib.pyplot as plt

Define base mesh (domain and finest discretization),

>>> dh = 5    # minimum cell width (base mesh cell width)
>>> nbc = 64  # number of base mesh cells
>>> h = dh * np.ones(nbc)
>>> mesh = TreeMesh([h, h])

Define corner points for a rectangular box, and subdived the mesh within the box to the maximum refinement level.

>>> x0s = [120.0, 80.0]
>>> x1s = [240.0, 160.0]
>>> levels = [mesh.max_level]
>>> mesh.refine_box(x0s, x1s, levels)

>>> mesh.plot_grid()
>>> plt.show()

(Source code, png, pdf)

Galleries and Tutorials using discretize.TreeMesh

Basic: PlotImage

Basic: PlotImage

QuadTree: FaceDiv

QuadTree: FaceDiv

QuadTree: Hanging Nodes

QuadTree: Hanging Nodes

Overview of Mesh Types

Overview of Mesh Types

Tree Meshes

Tree Meshes

Differential Operators

Differential Operators