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.- 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.
- 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()
).
- 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
- 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 withphase
equal to 0 in blue, and seeds withphase
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 withphase
equal to 0 in blue, and seeds withphase
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.