microstructpy.seeding package

class microstructpy.seeding.Seed(seed_geometry, phase=0, breakdown=None, position=None)

Bases: object

Seed particle

The Seed class contains the information about a single seed in the mesh. These seeds have a geometry (microstructpy.geometry), phase number, breakdown, and position.

Parameters:

• seed_geometry (from microstructpy.geometry) – The geometry of the seed.
• phase (int) – The phase number of the seed.
• breakdown (list or numpy.ndarray) –

  The circle/sphere approximation of this geometry. The format for this input is:

  #                 x   y  r
  breakdown_2D = [( 2,  3, 1),
                  ( 0,  0, 4),
                  (-2,  4, 8)]
  
  #                 x   y   z  r
  breakdown_3D = [( 3, -1,  2, 1),
                  ( 0,  2, -1, 1)]
  

  The default behavior is to call the approximate() function of the geometry.

• position (list or numpy.ndarray) – The coordinates of the seed. See position for more details.

classmethod factory(seed_type, phase=0, breakdown=None, position=None, **kwargs)

Factory method for seeds

This function returns a seed based on the seed type and keyword arguments associated with that type. The currently supported types are:

• circle
• ellipse
• ellipsoid
• rectangle
• sphere
• square

If the seed_type is not on this list, an error is thrown.

Parameters:

• seed_type (str) – type of seed, from list above.
• phase (optional, int) – Material phase number of seed.
• breakdown (optional, list) –

  List of circles or spheres that approximate the geometry. The list should be formatted as follows:

  breakdown = [(x1, y1, z1, r1), (x2, y2, z2, r2), ...]
  

  The breakdown will be automatically generated if not provided.

• position (optional, list) – The coordinates of the seed. Default is the origin.
• **kwargs – Keyword arguments that define the size, shape, etc of the seed geometry.

Returns:

An instance of the class.

Return type:

Seed

classmethod from_str(seed_str)

Create seed from a string.

This method creates a seed particle from a string representation. This is used when reading in seeds from a file.

Parameters:seed_str (str) – String representation of the seed. Returns:An instance of a Seed derived class.

plot(**kwargs)

Plot the seed

This function plots the geometry of the seed. The keyword arguments are passed through to matplotlib. See the plot methods in microstructpy.geometry for more details.

Parameters:**kwargs – Plotting keyword arguments.

plot_breakdown(**kwargs)

Plot breakdown of seed

This function plots the circle/sphere breakdown of the seed. In 2D, this adds a PatchCollection to the current axes.

Parameters:**kwargs – Matplotlib keyword arguments.

limits

The (lower, upper) bounds of the seed

Type:list

position

Position of the seed

This is the location of the seed center.

Note

If the breakdown of the seed has been populated, the setter function will update the position of the center and translate the breakdown circles/spheres.

volume

The area (2D) or volume (3D) of the seed

Type:float

class microstructpy.seeding.SeedList(seeds=[])

Bases: object

List of seed geometries.

The SeedList is similar to a standard Python list, but contains instances of the Seed class. It can be generated from a list of Seeds, by creating enough seeds to fill a given volume, or by reading the content of a cache text file.

Parameters:seeds (list) – List of Seed instances.

append(seed)

Append seed

This function appends a seed to the list.

Parameters:seed (Seed) – The seed to append to the list

extend(seeds)

Extend seed list

This function adds a list of seeds to the end of the seed list.

Parameters:seeds (list or SeedList) – List of seeds

classmethod from_file(filename)

Create seed list from file containing list of seeds

This function creates a seed list from a file containing a list of seeds. This file should contain the string representations of seeds, separated by a newline character (which is the behavior of write()).

Parameters:filename (str) – File containing the seed list. Returns:Instance of class. Return type:SeedList

classmethod from_info(phases, volume, rng_seeds={})

Create seed list from microstructure information

This function creates a seed list from information about the microstruture. The “phases” input should be a list of material phase dictionaries, formatted according to the Phase Dictionaries guide.

The “volume” input is the minimum volume of the list of seeds. Seeds will be added to the list until this volume threshold is crossed.

Finally, the “rng_seeds” input is a dictionary of random number generator (RNG) seeds for each parameter of the seed geometries. For example, if one of the phases uses “size” to define the seeds, then “size” could be a keyword of the “rng_seeds” input. The value should be a non-negative integer, to seed the RNG for size. The default RNG seed is 0.

Note

If two or more parameters have the same RNG seed and the same kernel of the distribution, those parameters will not be correlated. This method updates RNG seeds based on the order that distributions are sampled to avoid correlation between independent random variables.

Parameters:

• phases (dict) – Dictionary of phase information, see Phase Dictionaries for a guide.
• volume (float) – The total area/volume of the seeds in the list.
• rng_seeds (dict) – Dictionary of RNG seeds for each step in the seeding process.

Returns:

An instance of the class containing seeds prescribed by the phase information and filling the given volume.

Return type:

SeedList

plot(**kwargs)

Plot the seeds in the seed list.

This function plots the seeds contained in the seed list. In 2D, the seeds are grouped into matplotlib collections to reduce the computational load. In 3D, matplotlib does not have patches, so each seed is rendered as its own surface.

Additional keyword arguments can be specified and passed through to matplotlib. These arguments should be either single values (e.g. edgecolors='k'), or lists of values that have the same length as the seed list.

Parameters:**kwargs – Keyword arguments to pass to matplotlib

plot_breakdown(**kwargs)

Plot the breakdowns of the seeds in seed list.

This function plots the breakdowns of seeds contained in the seed list. In 2D, the breakdowns are grouped into matplotlib collections to reduce the computational load. In 3D, matplotlib does not have patches, so each breakdown is rendered as its own surface.

Additional keyword arguments can be specified and passed through to matplotlib. These arguments should be either single values (e.g. edgecolors='k'), or lists of values that have the same length as the seed list.

Parameters:**kwargs – Keyword arguments to pass to matplotlib

position(domain, pos_dists={}, rng_seed=0, hold=[], max_attempts=10000, rtol='fit', verbose=False)

Position seeds in a domain

This method positions the seeds within a domain. The “domain” should be a geometry instance from the microstructpy.geometry package.

The “pos_dist” input is for phases with custom position distributions, the default being a uniform random distribution. For example:

import scipy.stats
mu = [0.5, -0.2]
sigma = [[2.0, 0.3], [0.3, 0.5]]
pos_dists = {2: scipy.stats.multivariate_normal(mu, sigma),
             3: ['random',
                 scipy.stats.norm(0, 1)]
             }

Here, phases 0 and 1 have the default distribution, phase 2 has a bivariate normal position distribution, and phase 3 is uniform in the x and normally distributed in the y. Multivariate distributions are described on the scipy.stats website, in the multivariate distributions section.

The position of certain seeds can be held fixed during the positioning process using the “hold” input. This should be a list of booleans, where False indicates a seed should not be held fixed and True indicates that it should be held fixed. The default behavior is to not hold any seeds fixed.

The “rtol” parameter governs the relative overlap tolerable between seeds. Setting rtol to 0 means that there is no overlap, while a value of 1 means that one seed’s center is on the edge of another seed. The default value is ‘fit’, which determines a tolerance between 0 and 1 based on the ratio of standard deviation to mean in grain volumes.

Parameters:

• domain (from the microstructpy.geometry package) – The domain of the microstructure.
• pos_dists (dict, optional) – Position distributions for each phase, formatted like the example above.
• rng_seed (int, optional) – Random number generator (RNG) seed for positioning the seeds. Should be a non-negative integer.
• hold (list, optional) – List of booleans for holding the positions of seeds.
• max_attempts (int, optional) – Number of random trials before removing a seed from the list.
• rtol ('fit' or float) – The relative overlap tolerance between seeds. This parameter should be between 0 and 1. Using the ‘fit’ option, the function will pick a value for rtol based on the mean and standard deviation in seed volumes.
• verbose (bool) – This option will print a running counter of how many seeds have been positioned.

write(filename)

Write seed list to a text file

This function writes out the seed list to a file. The content of this file is human-readable and can be read by the from_file method.

Parameters:filename (str) – File to write the seed list.

Submodules

• microstructpy.seeding.seed module
• microstructpy.seeding.seedlist module