class microstructpy.meshing.TriMesh(points, elements, element_attributes=None, facets=None, facet_attributes=None)[source]

Bases: object

Triangle/Tetrahedron mesh.

The TriMesh class contains the points, facets, and elements in a triangle/ tetrahedron mesh, also called an unstructured grid.

The points attribute is an Nx2 or Nx3 list of points in the mesh. The elements attribute contains the Nx3 or Nx4 list of the points at the corners of each triangle/tetrahedron. A list of facets can also be included, though it is optional and does not need to include every facet in the mesh. Attributes can also be assigned to the elements and facets, though they are also optional.

  • points (list, numpy.ndarray) – List of coordinates in the mesh.

  • elements (list, numpy.ndarray) – List of indices of the points at the corners of each element. The shape should be Nx3 in 2D or Nx4 in 3D.

  • element_attributes (list, numpy.ndarray) – (optional) A number associated with each element. Defaults to None.

  • facets (list, numpy.ndarray) – (optional) A list of facets in the mesh. The shape should be Nx2 in 2D or Nx3 in 3D. Defaults to None.

  • facet_attributes (list, numpy.ndarray) – (optional) A number associated with each facet. Defaults to None.

classmethod from_file(filename)[source]

Read TriMesh from file.

This function reads in a triangular mesh from a file and creates an instance from that file. Currently the only supported file type is the output from write() with the format='str' option.


filename (str) – Name of file to read from.


An instance of the class.

Return type


classmethod from_polymesh(polymesh, phases=None, mesher='Triangle/Tetgen', min_angle=0, max_volume=inf, max_edge_length=inf, mesh_size=inf)[source]

Create TriMesh from PolyMesh.

This constuctor creates a triangle/tetrahedron mesh from a polygon mesh (PolyMesh). Polygons of the same seed number are merged and the element attribute is set to the seed number it is within. The facets between seeds are saved to the mesh and the index of the facet is stored in the facet attributes.

Since the PolyMesh can include phase numbers for each region, additional information about the phases can be included as an input. The “phases” input should be a list of material phase dictionaries, formatted according to the Phase Dictionaries guide.

The minimum angle, maximum volume, and maximum edge length options provide quality controls for the mesh. The phase type option can take one of several values, described below.

  • crystalline: granular, solid

  • amorphous: glass, matrix

  • void: crack, hole

The crystalline option creates a mesh where cells of the same seed number are merged, but cells are not merged across seeds. _This is the default material type._

The amorphous option creates a mesh where cells of the same phase number are merged to create an amorphous region in the mesh.

Finally, the void option will merge neighboring void cells and treat them as holes in the mesh.

  • polymesh (PolyMesh) – A polygon/polyhedron mesh.

  • phases (list) – (optional) A list of dictionaries containing options for each phase. Default is {'material_type': 'solid', 'max_volume': float('inf')}.

  • mesher (str) – {‘Triangle/TetGen’ | ‘Triangle’ | ‘TetGen’ | ‘gmsh’} specify the mesh generator. Default is ‘Triangle/TetGen’.

  • min_angle (float) – The minimum interior angle, in degrees, of an element. This option is used with Triangle or TetGen and in 3D is the minimum dihedral angle. Defaults to 0.

  • max_volume (float) – The default maximum cell volume, used if one is not set for each phase. This option is used with Triangle or TetGen. Defaults to infinity, which turns off this control.

  • max_edge_length (float) – The maximum edge length of elements along grain boundaries. This option is used with Triangle. Defaults to infinity, which turns off this control.

  • mesh_size (float) – The target size of the mesh elements. This option is used with gmsh. Default is infinity, whihch turns off this control.

plot(index_by='element', material=[], loc=0, **kwargs)[source]

Plot the mesh.

This method plots the mesh using matplotlib. In 2D, this creates a matplotlib.collections.PolyCollection and adds it to the current axes. In 3D, it creates a mpl_toolkits.mplot3d.art3d.Poly3DCollection and adds it to the current axes. The keyword arguments are passed though to matplotlib.

  • index_by (str) – (optional) {‘element’ | ‘attribute’} Flag for indexing into the other arrays passed into the function. For example, plot(index_by='attribute', color=['blue', 'red']) will plot the elements with element_attribute equal to 0 in blue, and elements with element_attribute equal to 1 in red. Note that in 3D the facets are plotted instead of the elements, so kwarg lists must be based on facets and facet_attributes. Defaults to ‘element’.

  • material (list) – (optional) Names of material phases. One entry per material phase (the index_by argument is ignored). If this argument is set, a legend is added to the plot with one entry per material. Note that the element_attributes in 2D or the facet_attributes in 3D must be the material numbers for the legend to be formatted properly.

  • loc (int or str) – (optional) The location of the legend, if ‘material’ is specified. This argument is passed directly through to matplotlib.pyplot.legend(). Defaults to 0, which is ‘best’ in matplotlib.

  • **kwargs – Keyword arguments that are passed through to matplotlib.

write(filename, format='txt', seeds=None, polymesh=None)[source]

Write mesh to file.

This function writes the contents of the mesh to a file. The format options are ‘abaqus’, ‘tet/tri’, ‘txt’, and ‘vtk’. See the Triangular Mesh section of the Output File Formats guide for more details on these formats.

  • filename (str) – The name of the file to write. In the cases of TetGen/Triangle, this is the basename of the files.

  • format (str) – {‘abaqus’ | ‘tet/tri’ | ‘txt’ | ‘vtk’} (optional) The format of the output file. Default is ‘txt’.

  • seeds (SeedList) – (optional) List of seeds. If given, VTK files will also include the phase number of of each element in the mesh. This assumes the element_attributes field contains the seed number of each element.

  • polymesh (PolyMesh) – (optional) Polygonal mesh used for generating the triangular mesh. If given, will add surface unions to Abaqus files - for easier specification of boundary conditions.