microstructpy.cli module¶

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(raw_in, filepath='.')[source]¶

Convert dictionary from xmltodict

This function converts the dictionary created by xmltodict. The input is an ordered dictionary, where the keys are strings and the items are either strings, lists, or ordered dictionaries. Strings occur are the “leaves” of the dictionary and are converted into values using microstructpy._misc.from_str(). Lists are return with each of their elements converted into values. Ordered dictionaries are converted by (recursively) calling this function.

Parameters:	raw_in – unconverted input- either dict, list, or str filepath (str, optional) – filepath of input XML, to resolve relative paths in the input file
Returns:	A copy of the input where the strings have been converted

microstructpy.cli.main()[source]¶: CLI calling function

microstructpy.cli.plot_poly(pmesh, phases, plot_files=[], plot_axes=True, color_by='material', colormap='viridis', **edge_kwargs)[source]¶

microstructpy.cli.plot_seeds(seeds, phases, domain, plot_files=[], plot_axes=True, color_by='material', colormap='viridis', **edge_kwargs)[source]¶

microstructpy.cli.plot_tri(tmesh, phases, seeds, pmesh, plot_files=[], plot_axes=True, color_by='material', colormap='viridis', **edge_kwargs)[source]¶

microstructpy.cli.read_input(filename)[source]¶

microstructpy.cli.run(phases, domain, verbose=False, restart=True, directory='.', filetypes={'poly': 'txt', 'seeds': 'txt', 'tri': 'txt'}, rng_seeds={'a': 1243886740, 'angle': 211506867, 'angle_deg': 1248676725, 'aspect_ratio': 2009100301, 'b': 1312539098, 'diameter': 54978771, 'orientation': 921030759, 'phase': 1316468120, 'size': 2005296531, 'volume': 59498092}, 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 (dict or list) –

A dictionary or list of dictionaries for each material phase. The dictionary entries depend on the shape of the seeds, but one example is:

phase1 = {'name': 'foam',
         'material_type': 'amorphous',
         'volume': 0.25,
         'shape': 'sphere',
         'd': scipy.stats.lognorm(s=0.4, scale=1)
         }

phase2 = {'name': 'voids',
          'material_type': 'void',
          'volume': 0.75,
          'shape': 'sphere',
          'r': 1
          }

phases = [phase1, phase2]

The entries can be either constants ('r': 1) or distributed, ('d': scipy.stats.lognorm(s=0.4, scale=1)).

The entries can be either constants ('radius': 1) or distributed, ('diameter': scipy.stats.lognorm(s=0.4, scale=0.5)). The following non-shape keywords can be used in each phase:

Non-Shape Phase Keywords¶
Keyword	Default	Notes
color	C<n>	Can be any matplotlib color. Defaults to the standard matplotlib color cycle. More info on the matplotlib Specifying Colors page.
material_type	crystalline	Options: crystalline, granular, solid, amorphous, glass matrix, void, crack, hole. (Non-bolded words are alies for the bolded words.)
name	Material <n>	Can be non-string variable.
position	uniform	Uniform random distribution, see below for options.
fraction	1	Can be proportional volumes (such as 1:3) or fractions (such as 0.1, 0.2, and 0.7). Can also be a scipy.stats distribution. Volume fractions are normalized by their sum.

The position distribution of the phase can be customized for non-randomly sorted phases. For example:

# independent distributions for each axis
position = [0,
            scipy.stats.uniform(0, 1),
            scipy.stats.uniform(0.25, 0.5)]

# correlated position distributions
mu = [2, 3]
sigma = [[3, 1], [1, 4]]
position = scipy.stats.multivariate_normal(mu, sigma)

domain (class from microstructpy.geometry) – The geometry of the domain.
verbose (bool) – Option to run in verbose mode. Prints status updates to the terminal. Defaults to False.
restart (bool) – 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) – 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) –

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) –

The random number generator (RNG) seeds. The dictionary values should all be non-negative integers. 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) –
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) – 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. Should be stritly positive.
mesh_min_angle (float) – 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. Should be in the range 0-60.
mesh_max_edge_length (float) – The maximum edge length of elements along grain boundaries. Currently only supported in 2D.
plot_axes (bool) – 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) – Option to verify the output mesh against the input phases.
color_by (str) – Method for coloring seeds and grains in the output plots. The options are {‘material’, ‘seed number’, ‘material number’}. For ‘material’, the color field of each phase is used. For ‘seed number’ and ‘material number’, the seeds are colored using the colormap specified in the ‘colormap’ keyword argument.
colormap (str) – Name of the colormap used to color the seeds and grains if ‘color_by’ is set to ‘seed number’ or ‘material number’. A full explanation of the matplotlib colormaps is availabe at Choosing Colormaps in Matplotlib.
seeds_kwargs (dict) – Optional keyword arguments for plotting seeds. For example, the line width and color.
poly_kwargs (dict) – Optional keyword arguments for plotting polygonal meshes. For example, the line width and color.
tri_kwargs (dict) – Optional keyword arguments for plotting triangular meshes. For example, the line width and color.

microstructpy.cli.run_file(filename)[source]¶

microstructpy.cli.unpositioned_seeds(phases, domain, rng_seeds={})[source]¶

microstructpy.cli module¶

MicroStructPy

Navigation

Related Topics