microstructpy.cli¶
Command Line Interface.
This module contains the command line interface (CLI) for MicroStructPy. The CLI primarily reads XML input files and creates a microstructure according to those inputs. It can also run demo input files.

microstructpy.cli.
dict_convert
(dictionary, filepath='.')[source]¶ Convert dictionary from xmltodict
The xmltodict
parse
method creates dictionaries with values that are all strings, rather than strings, floats, ints, etc. This function recursively searches the dictionary for string values and attempts to convert the dictionary values.If a dictionary contains the key
dist_type
, it is assumed that the corresponding name is ascipy.stats
statistical distribution and the remaining keys are inputs for that distribution, with two exceptions. First, if the value ofdist_type
iscdf
, then the remaining key should befilename
and its value should be the path to a CSV file, where each row contains the (x, CDF) points along the CDF curve. Second, if the value ofdist_type
ishistogram
, then the remaining key should also befilename
and its value should be the path to a CSV file. For the histogram, the first row of this CDF should be the n bin heights and the second row should be the n+1 bin locations.Additionally, if a key in the dictionary contains
filename
ordirectory
and the value associated with that key is a relative path, then the filepath is converted from a relative to an absolute path using thefilepath
input as the reference point. This behavior can be switched off by settingfilepath=False
. Parameters
dictionary (list, dict, or collections.OrderedDict) – Dictionary or dictionaries to be converted.
filepath (str) – (optional) Reference path to resolve relative paths.
 Returns
A copy of the input where the string values have been converted. If only one dict is passed into the function, then an instance of
collections.OrderedDict
is returned. Return type

microstructpy.cli.
input2dict
(filename, root_tag='input')[source]¶ Read input file into a dictionary
This function reads an input file and creates a dictionary of strings contained within the file.
 Parameters
filename – Name of the input file.
 Returns
Dictionary of input strings.
 Return type

microstructpy.cli.
plot_poly
(pmesh, phases, plot_files=['polymesh.png'], plot_axes=True, color_by='material', colormap='viridis', **edge_kwargs)[source]¶ Plot polygonal/polyhedral mesh
This function creates formatted plots of a
PolyMesh
. Parameters
pmesh (PolyMesh) – Polygonal mesh to plot.
phases (list) – List of phase dictionaries. See Phase Dictionaries for more details.
plot_files (list) – (optional) List of files to save the output plot. Defaults to saving the plot to
polymesh.png
.plot_axes (bool) – (optional) Flag to turn the axes on or off. True shows the axes, False removes them. Defaults to True.
color_by (str) – (optional) {‘material’  ‘seed number’  ‘material number’} Option to choose how the polygons/polyhedra are colored. Defaults to ‘material’.
colormap (str) – (optional) Name of the matplotlib colormap to color the seeds. Ignored if color_by=’material’. Defaults to ‘viridis’, the standard matplotlib colormap. See Choosing Colormaps in Matplotlib for more details.
**edge_kwargs – Additional keyword arguments that will be passed to
PolyMesh.plot_facets()
in 2D andPolyMesh.plot()
in 3D.

microstructpy.cli.
plot_seeds
(seeds, phases, domain, plot_files=[], plot_axes=True, color_by='material', colormap='viridis', **edge_kwargs)[source]¶ Plot seeds
This function creates formatted plots of a
SeedList
. Parameters
seeds (SeedList) – Seed list to plot.
phases (list) – List of phase dictionaries. See Phase Dictionaries for more details.
domain (from
microstructpy.geometry
) – Domain geometry.plot_files (list) – (optional) List of files to save the output plot. Defaults to saving the plot to
seeds.png
.plot_axes (bool) – (optional) Flag to turn the axes on or off. True shows the axes, False removes them. Defaults to True.
color_by (str) – (optional) {‘material’  ‘seed number’  ‘material number’} Option to choose how the polygons/polyhedra are colored. Defaults to ‘material’.
colormap (str) – (optional) Name of the matplotlib colormap to color the seeds. Ignored if color_by=’material’. Defaults to ‘viridis’, the standard matplotlib colormap. See Choosing Colormaps in Matplotlib for more details.
**edge_kwargs – additional keyword arguments that will be passed to
SeedList.plot()
.

microstructpy.cli.
plot_tri
(tmesh, phases, seeds, pmesh, plot_files=[], plot_axes=True, color_by='material', colormap='viridis', **edge_kwargs)[source]¶ Plot seeds
This function creates formatted plots of a
TriMesh
. Parameters
tmesh (TriMesh) – Triangular mesh to plot.
phases (list) – List of phase dictionaries. See Phase Dictionaries for more details.
seeds (SeedList) – List of seed geometries.
pmesh (PolyMesh) – Polygonal mesh from which
tmesh
was generated.plot_files (list) – (optional) List of files to save the output plot. Defaults to saving the plot to
trimesh.png
.plot_axes (bool) – (optional) Flag to turn the axes on or off. True shows the axes, False removes them. Defaults to True.
color_by (str) – (optional) {‘material’  ‘seed number’  ‘material number’} Option to choose how the polygons/polyhedra are colored. Defaults to ‘material’.
colormap (str) – (optional) Name of the matplotlib colormap to color the seeds. Ignored if color_by=’material’. Defaults to ‘viridis’, the standard matplotlib colormap. See Choosing Colormaps in Matplotlib for more details.
**edge_kwargs – Additional keyword arguments that will be passed to
TriMesh.plot()
.

microstructpy.cli.
read_input
(filename)[source]¶ Convert input file to dictionary
This function reads an input file and parses it into a dictionary.
 Parameters
filename (str) – The name of an XML input file.
 Returns
Dictionary of run inputs.
 Return type

microstructpy.cli.
run
(phases, domain, verbose=False, restart=True, directory='.', filetypes={'poly': ['txt', 'txt'], 'seeds': ['txt', 'txt'], 'tri': ['txt', 'txt']}, rng_seeds={'a': 1774552273, 'angle': 2116865706, 'angle_deg': 723589714, 'area': 1486701603, 'aspect_ratio': 413080424, 'b': 1189609856, 'diameter': 153513816, 'phase': 1250098819, 'size': 312261726, 'volume': 966719902}, plot_axes=True, rtol='fit', edge_opt=False, edge_opt_n_iter=100, mesher='Triangle/TetGen', mesh_max_volume=inf, mesh_min_angle=0, mesh_max_edge_length=inf, mesh_size=inf, verify=False, color_by='material', colormap='viridis', seeds_kwargs={}, poly_kwargs={}, tri_kwargs={})[source]¶ Run MicroStructPy
This is the primary run function for the package. It performs these steps:
Create a list of unpositioned seeds
Position seeds in domain
Create a polygon mesh from the seeds
Create a triangle mesh from the polygon mesh
(optional) Perform mesh verification
 Parameters
phases (list or dict) – Single phase dictionary or list of multiple phase dictionaries. See Phase Dictionaries for more details.
domain (from
microstructpy.geometry
) – The geometry of the domain.verbose (bool) – (optional) Option to run in verbose mode. Prints status updates to the terminal. Defaults to False.
restart (bool) – (optional) Option to run in restart mode. Saves caches at the end of each step and reads caches to restart the analysis. Defaults to True.
directory (str) – (optional) File path where outputs will be saved. This path can either be relative to the current directory, or an absolute path. Defaults to the current working directory.
filetypes (dict) –
(optional) Filetypes for the output files. A dictionary containing many of the possible file types is:
filetypes = {'seeds': 'txt', 'seeds_plot': ['eps', 'pdf', 'png', 'svg'], 'poly': ['txt', 'ply', 'vtk'], 'poly_plot': 'png', 'tri': ['txt', 'abaqus', 'vtk'], 'tri_plot': ['png', 'pdf'], 'verify_plot': 'pdf' }
If an entry is not included in the dictionary, then that output is not saved. Default is an empty dictionary. If restart is True, then ‘txt’ is added to the ‘seeds’, ‘poly’, and ‘tri’ fields.
rng_seeds (dict) –
(optional) The random number generator (RNG) seeds. The dictionary values should all be nonnegative integers. Specifically, RNG seeds should be convertible to NumPy uint32. An example dictionary is:
rng_seeds = {'fraction': 0, 'phase': 134092, 'position': 1, 'size': 95, 'aspect_ratio': 2, 'orienation': 2 }
If a seed is not specified, the default value is 0.
(optional) The relative overlap tolerance between seeds. This parameter should be between 0 and 1. The condition for two circles to overlap is:
\[ x_2  x_1  + \text{rtol} \min(r_1, r_2) < r_1 + r_2\]The default value is
'fit'
, which uses the mean and variance of the size distribution to estimate a value for rtol.edge_opt (bool) – (optional) This option will maximize the minimum edge length in the PolyMesh. The seeds associated with the shortest edge are displaced randomly to find improvement and this process iterates until n_iter attempts have been made for a given edge. Defaults to False.
edge_opt_n_iter (int) – (optional) Maximum number of iterations per edge during optimization. Ignored if edge_opt set to False. Defaults to 100.
mesher (str) – {‘raster’  ‘Triangle/TetGen’  ‘Triangle’  ‘TetGen’  ‘gmsh’} specify the mesh generator. Default is ‘Triangle/TetGen’.
mesh_max_volume (float) – (optional) The maximum volume (area in 2D) of a mesh cell in the triangular mesh. Default is infinity, which turns off the maximum volume quality setting. Value should be strictly positive.
mesh_min_angle (float) – (optional) The minimum interior angle, in degrees, of a cell in the triangular mesh. For 3D meshes, this is the dihedral angle between faces of the tetrahedron. Defaults to 0, which turns off the angle quality constraint. Value should be in the range 060.
mesh_max_edge_length (float) – (optional) The maximum edge length of elements along grain boundaries. Currently only supported in 2D.
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_axes (bool) – (optional) Option to show the axes in output plots. When False, the plots are saved without axes and very tight borders. Defaults to True.
verify (bool) – (optional) Option to verify the output mesh against the input phases. Defaults to False.
color_by (str) – (optional) {‘material’  ‘seed number’  ‘material number’} Option to choose how the polygons/polyhedra are colored. Defaults to ‘material’.
colormap (str) – (optional) Name of the matplotlib colormap to color the seeds. Ignored if color_by=’material’. Defaults to ‘viridis’, the standard matplotlib colormap. See Choosing Colormaps in Matplotlib for more details.
seed_kwargs (dict) – additional keyword arguments that will be passed to
SeedList.plot()
.poly_kwargs (dict) – Additional keyword arguments that will be passed to
PolyMesh.plot_facets()
in 2D andPolyMesh.plot()
in 3D.tri_kwargs (dict) – Additional keyword arguments that will be passed to
TriMesh.plot()
.