# 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 a scipy.stats statistical distribution and the remaining keys are inputs for that distribution, with two exceptions. First, if the value of dist_type is cdf, then the remaining key should be filename 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 of dist_type is histogram, then the remaining key should also be filename and its value should be the path to a CSV file. For the histogram, the first row of this CDF should be the n+1 bin locations and the second row should be the n bin heights.

Additionally, if a key in the dictionary contains filename or directory and the value associated with that key is a relative path, then the filepath is converted from a relative to an absolute path using the filepath input as the reference point. This behavior can be switched off by setting filepath=False.

Parameters: dictionary (list, dict, or collections.OrderedDict) – Dictionary or dictionaries to be converted. filepath (str) – (optional) Reference path to resolve relative paths. 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.
microstructpy.cli.main()[source]

CLI calling function

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 and PolyMesh.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 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 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 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 TriMesh.plot().

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. Dictionary of run inputs. collections.OrderedDict
microstructpy.cli.run(phases, domain, verbose=False, restart=True, directory='.', filetypes={}, rng_seeds={}, plot_axes=True, rtol='fit', mesh_max_volume=inf, mesh_min_angle=0, mesh_max_edge_length=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 un-positioned 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 non-negative 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. rtol (float or str) – (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. 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 stritly 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 0-60. mesh_max_edge_length (float) – (optional) The maximum edge length of elements along grain boundaries. Currently only supported in 2D. 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 and PolyMesh.plot() in 3D. tri_kwargs (dict) – Additional keyword arguments that will be passed to TriMesh.plot().
microstructpy.cli.run_file(filename)[source]

Run an input file

This function reads an input file and runs it through the standard workflow.

Parameters: filename (str) – The name of an XML input file.