# discretize.TreeMesh#

class discretize.TreeMesh(h=None, origin=None, diagonal_balance=False, **kwargs)[source]#

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 effect all calls to refine the tree.

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()
```

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

Methods

 Average matrix for cell center to total (including hanging) x faces. Average matrix for cell center to total (including hanging) y faces. 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. 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 along a line segment defined by two 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 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 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) 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_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. Represent the mesh's attributes as a dictionary. `setCellGradBC`(*args, **kwargs) setCellGradBC has been removed. Set boundary conditions for derivative operators acting on cell-centered quantities. `toVTK`([models]) Convert mesh (and models) to corresponding VTK or PyVista data object. 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. 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.

Basic: PlotImage

Basic: PlotImage