# 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 bin heights and the second row should be the n+1 bin locations.

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.

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

collections.OrderedDict

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 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().

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

collections.OrderedDict

microstructpy.cli.run(phases, domain, verbose=False, restart=True, directory='.', filetypes={'poly': ['txt', 'txt'], 'seeds': ['txt', 'txt'], 'tri': ['txt', 'txt']}, rng_seeds={'a': 1710031536, 'angle': 1838993140, 'angle_deg': 1499295860, 'area': 273649789, 'aspect_ratio': 615769720, 'b': 1950859448, 'diameter': 1321109759, 'phase': 1290586737, 'size': 1308012108, 'volume': 552743383}, 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 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.

• 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 0-60.

• 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 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.