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

Raster mesh.

The RasterMesh class contains the points and elements in a raster mesh, also called an regular grid.

The points attribute is an Nx2 or Nx3 list of points in the mesh. The elements attribute contains the Nx4 or Nx8 list of the points at the corners of each pixel/voxel. 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.


numpy.ndarray containing element attributes.

Array contains -1 where there are no elements (e.g. circular domains).


element_attributes (bool) – (optional) Flag to return element attributes in the array. Set to True return attributes and set to False to return element indices. Defaults to True.


Array of values of element atttributes, or indices.

Return type


classmethod from_file(filename)

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, mesh_size, phases=None)[source]

Create RasterMesh from PolyMesh.

This constuctor creates a raster 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 mesh_size option determines the side length of each pixel/voxel. Element attributes are sampled at the center of each pixel/voxel. If an edge of a domain is not an integer multiple of the mesh_size, it will be clipped. For example, if mesh_size is 3 and an edge has bounds [0, 11], the sides of the pixels will be at 0, 3, 6, and 9 while the centers of the pixels will be at 1.5, 4.5, 7.5.

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.

  • mesh_size (float) – The side length of each pixel/voxel.

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

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.axes3d.Axes3D.voxels() 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. 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 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’, ‘txt’, and ‘vtk’. See the Triangular Mesh section of the Output File Formats guide for more details on these formats.

VTK files use the RECTILINEAR_GRID data type.

  • filename (str) – The name of the file to write.

  • format (str) – {‘abaqus’ | ‘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 raster mesh. If given, will add surface unions to Abaqus files - for easier specification of boundary conditions.

property mesh_size

Side length of elements.