Python Package Guide¶

The python package for MicroStructPy includes the following classes:

microstructpy
├─ geometry
│  ├─ Box
│  ├─ Cube
│  ├─ Circle
│  ├─ Ellipse
│  ├─ Ellipsoid
│  ├─ Rectangle
│  ├─ Square
│  └─ Sphere
├─ seeding
│  ├─ Seed
│  └─ SeedList
└─ meshing
   ├─ PolyMesh
   └─ TriMesh

Seeds are given a geometry and a material number, SeedLists are lists of Seeds, the PolyMesh can be created from a SeedList, and finally the TriMesh can be created from a PolyMesh. This is the flow of information built into the MicroStructPy command line interface (CLI). Custom algorithms for seeding or meshing can be implemented using the classes above and a few key methods.

The following describes the 3-step process of generating a microstructure mesh in MicroStructPy, including the relevant classes and methods. For a complete list of MicroStructPy classes, visit the API page. Visit the Examples page for examples using the API.

0. List of Seed Geometries¶

The list of seed geometries is a SeedList. The SeedList can be created from a list of Seed instances, which each contain a geometry and a phase.

A SeedList can also be generated from a list of material phase dictionaries and a total seed volume using the SeedList.from_info() class method. The default seed volume is the volume of the domain. For more information on how to format the phase information, see the Phase Dictionaries below.

One convenience function is Seed.factory(), which takes in a geometry name and keyword arguments and returns a Seed with that geometry.

1. Pack Geometries into Domain¶

The standard domain is a geometry from the microstructpy.geometry package. To pack the geometries into the domain, the centers of the seeds are specified such that there is a tolerable about of overlap with other seeds, if any.

The standard method for positioning seeds in a domain is SeedList.position(). This function updates the Seed.position property of each Seed in the SeedList. The centers of all the seeds are within the domain geometry.

2. Tessellate the Domain¶

A tessellation of the domain divides its interior into polygonal/polyhedral cells with no overlap or gaps between them. This tessellation is stored in a PolyMesh class. The default method for creating a PolyMesh from a positioned list of seeds and a domain is PolyMesh.from_seeds(). This method creates a Voronoi-Laguerre diagram using the Voro++ package. Note that the only supported 3D domains are cubes and boxes.

3. Unstructured Meshing¶

Unstructured (triangular or tetrahedral) meshes can be used in finite element software to analyze the behavior of the microstructure. Their data are contained in the TriMesh class. This mesh can be created from a polygonal tessellation using the TriMesh.from_polymesh() method. The mesh can be output to several different file formats.

The unstructured meshes are generated using Triangle in 2D, TetGen in 3D, and MeshPy is the wrapper.

File I/O¶

There are file read and write functions associated with each of the classes listed above.

The read methods are:

The write methods are:

The read functions currently only support reading cache text files. The SeedList only writes to cache text files, while PolyMesh and TriMesh can output to several file formats.

Plotting¶

The SeedList, PolyMesh, and TriMesh classes have the following plotting methods:

These functions operate like the matplotlib plt.plot function in that they just plot to the current figure. You still need to add plt.axis('equal'), plt.show(), etc to format and view the plots.

Phase Dictionaries¶

Functions with phase information input require a list of dictionaries, one for each material phase. The dictionaries should be organized in a manner similar to the example below.

phase = {
       'name': 'Example Phase',
       'color': 'blue',
       'material_type': 'crystalline',
       'fraction': 0.5,
       'max_volume': 0.1,
       'shape': 'ellipse',
       'size': 1.2,
       'aspect_ratio': 2
}

The dictionary contains both data about the phase as a whole, such as its volume fraction and material type, and about the individual grains. The keywords size and aspect_ratio are keyword arguments for defining an Ellipse, so those are passed through to the Ellipse class when creating the seeds. For a non-uniform size (or aspect ratio) distribution, replace the constant value with a SciPy statistical distribution. For example:

import scipy.stats
size_dist = scipy.stats.uniform(loc=1, scale=0.4)
phase['size'] = size_dist

The max_volume option allows for maximum element volume controls to be phase-specific.