microstructpy.seeding.SeedList

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

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) – (optional) List of Seed instances.

append(seed)[source]

Append seed

This function appends a seed to the list.

Parameters

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

extend(seeds)[source]

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)[source]

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={})[source]

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

    (optional) Dictionary of RNG seeds for each step in the seeding process. The dictionary keys should match shape parameters in phases. For example:

    rng_seeds = {
        'size': 0,
        'angle': 3,
    }
    

Returns

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

Return type

SeedList

plot(index_by='seed', material=[], loc=0, **kwargs)[source]

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
  • index_by (str) – (optional) {‘material’ | ‘seed’} Flag for indexing into the other arrays passed into the function. For example, plot(index_by='material', color=['blue', 'red']) will plot the seeds with phase equal to 0 in blue, and seeds with phase equal to 1 in red. Defaults to ‘seed’.

  • material (list) – (optional) Names of material phases. One entry per material phase (the index_by argument is ignored). If this argument is set, a legend is added to the plot with one entry per material.

  • loc (int or str) – (optional) The location of the legend, if ‘material’ is specified. This argument is passed directly through to matplotlib.pyplot.legend(). Defaults to 0, which is ‘best’ in matplotlib.

  • **kwargs – Keyword arguments to pass to matplotlib

plot_breakdown(index_by='seed', material=[], loc=0, **kwargs)[source]

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
  • index_by (str) – (optional) {‘material’ | ‘seed’} Flag for indexing into the other arrays passed into the function. For example, plot(index_by='material', color=['blue', 'red']) will plot the seeds with phase equal to 0 in blue, and seeds with phase equal to 1 in red. Defaults to ‘seed’.

  • material (list) – (optional) Names of material phases. One entry per material phase (the index_by argument is ignored). If this argument is set, a legend is added to the plot with one entry per material.

  • loc (int or str) – (optional) The location of the legend, if ‘material’ is specified. This argument is passed directly through to matplotlib.pyplot.legend(). Defaults to 0, which is ‘best’ in matplotlib.

  • **kwargs – Keyword arguments to pass to matplotlib

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

Position seeds in a domain

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

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 in the multivariate section of the scipy.stats documentation.

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 microstructpy.geometry) – The domain of the microstructure.

  • pos_dists (dict) – (optional) Position distributions for each phase, formatted like the example above. Defaults to uniform random throughout the domain.

  • rng_seed (int) – (optional) Random number generator (RNG) seed for positioning the seeds. Should be a non-negative integer.

  • hold (list or numpy.ndarray) – (optional) List of booleans for holding the positions of seeds. Defaults to False for all seeds.

  • max_attempts (int) – (optional) Number of random trials before removing a seed from the list. Defaults to 10,000.

  • rtol (str or float) – (optional) The relative overlap tolerance between seeds. This parameter should be between 0 and 1. Using the ‘fit’ option, a function will determine the value for rtol based on the mean and standard deviation in seed volumes.

  • verbose (bool) – (optional) This option will print a running counter of how many seeds have been positioned. Defaults to False.

write(filename, format='txt')[source]

Write seed list to a text file

This function writes out the seed list to a file. The format of the file can be either ‘txt’ or ‘vtk’. The content of the ‘txt’ file is human-readable and can be read by the SeedList.from_file() method. The ‘vtk’ option creates a VTK legacy file with the grain geometries.

For grains that are non-spherical, the spherical breakdown of the seed is output instead of the seed itself.

Parameters

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