upxo.parswep.mcgs2d_parameter_sweeping module

class upxo.parswep.mcgs2d_parameter_sweeping.parameter_sweep(use_default_values=False, study='gs_analysis')[source]

Bases: object

This is a core UPXO class. Use to generate and work with multiple mcgs using a combination of various generating and controlling parameters.

Targetted at:

  • research: understanding algorithm sensitivity

  • research: understanding parameter sensitivity

  • research: understanding grain growth evolution

  • development: UPXO

Data structures:

  • Each PXTAl object is stored in a DICT under the instance number key.

  • Most properties are stored as Pandas dataframes.

  • The user input parameters are preserved under self.uiAAAAA,

where, AAAAA is the additional name string of the corresponsing parameter set. * Mesh instances are stored seperately as a DICT under the instance number key, followed by a nested DICT under the mcstep key.

Data attributes:

domain: Size of the domain dim: dimensionality gmp: global morphological parameters qmp: Q-partitioned morphological parameters purge_previous: Purge previous study objects save_sims: BOOL: flag to pickle raw databases of simulations __GENLOCK__: str: flag to lock simulation capability of UPXO

__GENLOCK__:

If ‘locked’, no simulations will be performed and grain structures will not be developed. Otherwise, if ‘open’. Status set to ‘locked’ whenever following cases:

  • when user input validation fails.

  • when computations branch towards any lock imposed by developer

in UPXO internals.

property info_message_display_level

Info message display level.

property info_message_display_level_simple

Info message display level simple.

property info_message_display_level_detailed

Info message display level detailed.

limit_check()[source]

Limit check.

generate_mcgs2d()[source]

Generate mcgs2d.

characterize_gs()[source]

Characterize gs.

initialize(N=2)[source]

Initialize.

run(char_post_sim=True, parallel_char=False)[source]

Sweeps across pipelines to achieve as per user request, across all allowed and possible combination of individual and sets of various parameters. Will only be consideref if defaults is True. The default is False.

char_post_sim:

Characterize during sims or post sims

parallel_char:

Parallelise characterization. Only if char_post_sim=True If parchar=False, characterization GS will not be characterized, in which case, use the characterize method explicitly.

assemble_locks()[source]

Assemble locks.

set_param_grid(domain_size=((0, 100), (0, 100), (0, 0), 1), read_from_file=False, filename=None)[source]

Set up the parameters pertaining to grid. Targetted at ps.gsi[:].uigrid

Parameters:

domain_size (list/tuple/deque/np.ndarray, optional) – ((x bounds), (y bounds), (z bounds), pixel size or increment). A bound is specified by two values, minimum and maximum. First value MUST be the numerically lower number. As no checks are made to validate this user entry, user must take care to enter these values. NOTE: pixel size will be uniform across x, y and z axes. The default is ((0, 100), (0, 100), (0, 0), 1).

Return type:

None.

set_param_sim(mcsteps=20, nstates=32, solver='python', tgrad=None, algo_hop=False, default_mcalg='200', algo_hops=[(200, 10), (201, 40), (202, 100)], save_at_mcsteps=numpy.linspace, state_sampling_scheme='rejection', consider_boltzmann_probability=False, s_boltz_prob='q_related', boltzmann_temp_factor_max=0.1, boundary_condition_type='wrapped', NL=1, kineticity='static', purge_previous=False, read_from_file=False, filename=None)[source]

Explanation

This is part of parameter setting methods for parameter sweep studies. Helps set grain structure simulation parameters like. The followig parameters are set by set_param_sim:

  • mcsteps

  • nstates

  • solver

  • tgrad

  • algo_hop

  • algo_hops

  • save_at_mcsteps

  • purge_previous

Usage

UPXO internal and user. Will be used if the user prefers quick parameter sweep with default values. If user, user wishes to have specirfic values, which would be most often the case.

param mcsteps:

Number of Monte-Carlo steps. To restrict comparisons over different temporal scales, all grain structure instances will be simulated upto equal mcsteps. NOTE: However, if in a case, the grain structure temporally saturates during simulation before the total mcsteps for that specific gsi is reaced, then the total number of mcsteps actyually covered would be smaller than that specified by the user. This is becvause, all core-solver algorithms in UPXO are designed to STOP when the grain structure reaces temporal saturation. This saturation happens when there is a single grain in the GS, that is all state values in the gs lattice become same. The default is 20.

type mcsteps:

int, optional

param nstates:

The total number of unique state values in the simulation. A value of 2 would basically generate an Ising type lattice. The default is 32.

type nstates:

int, optional

param solver:

Specifies whether the solver is to be from python or C. The choice depens on the following parameters:

  • Size of the spatial domain

  • Total number of mcsteps

  • Computational cost of the algorithm

The decision between ‘python’ and ‘c’ should happen based on simulation domain largness, which depend on the largeness of the spatial domain, largeness of the temporal dimension and finally largeness of the computational cost. Input is case-independent. Choosing ‘C’ will force UPXO to use the C-executatable for core solver. This option is only ava8ilable fo0r some algorithms. To know supported algorithms, please refer to info on algorithms. Choosing ‘python’ will make UPXO to decide between ‘python’ and ‘c’, based on practicality of using ‘python’ for large simulation domains. The default option is ‘python’

type solver:

str, optional

param tgrad:

Temperature gradient field of size. Size same as that of grid of lattice or that of the state value matrix. Each lattice point must accompanied by a temperature value. The default is None.

type tgrad:

np.ndarray, optional

param algo_hop:

This helps decide whether to use a single algorithm for the entire temporal domain or whether you would need UPXO to hop across algorithms. If False: disallow algorithm hopping If True: allow algorithm hopping If str: only allowed value as of now is ‘auto’. If ‘auto’: UPXO will decide which algorithms to use upon need of a algorithm hopping. The default is False.

type algo_hop:

bool/str, optional

param algo_hops:

1. If options pertaining to algorithm hopping has been provided by the user, then the first available option pertaining to algorithm ID will be used to set the algorithm. For example, if algo_hops is [(200, 10), (201, 40), (202, 100)], then mcalg will be set to ‘200’. 2. If a numerical entry has been made (in a case where the user has done through direct access through set_param_sim), then if it is valid, then str(value) will be set for mcalg. If invalid, mcalg will default to ‘200’ for each hop. 3. If a string entry has been made (in a case where the user has done through direct access through set_param_sim), then if it is valid, then it will be set for mcalg. If invalid, mcalg will default to ‘200’

The default is [(200, 10), (201, 40), (202, 100)], meaning:

algo200, upto 10% sim time algo201, upto 40% sim time algo202, upto 100% sim time

type algo_hops:

list/str/int, optional

param save_at_mcsteps:

DESCRIPTION. The default is np.linspace(0, 20, 5).

type save_at_mcsteps:

ITERABLE, optional

rtype:

None.

set_param_gsc(char_grains=True, char_stage='postsim', library='scikit-image', parallel=True, find_gbseg=True, g_area=True, gb_length=True, gb_length_crofton=True, gb_njp_order=True, g_eq_dia=True, g_feq_dia=True, g_solidity=True, g_circularity=True, g_mjaxis=True, g_mnaxis=True, g_morph_ori=True, g_el=True, g_ecc=True, read_from_file=False, filename=None)[source]

Set flags for grain structure characterisaiton and analysis.

Parameters:

  • char_grains (bool, optional) – Flag to charatcterize grains. If True, grains will be characterised and not if False. If True, grain boundaries will also be characterised for basic properties. Once the grains have been identifies, the characterisation will be done using scikit-image by default, at this version of UPXO. The default is False.

  • char_stage (str, optional) –

    Choose when to characterize the grains. Options include:

    • ’postsim’

    • ’insim’

    If ‘postsim’, grain structure will be characterised after all temporal slices have been extracted i.e. after all monte-carlo iterations have been completed. If ‘insim’, grain structure will be charactersed at the end of each monte-carlo iteration. The default is ‘postsim’.

  • library (str, optional) –

    Choose which library to identifying the grains. Options include:

    • scikit-image: 2D and 3D

    • opencv: 2D only

    • upxo: 2d only (deprecated)

    The default is ‘scikit-image’.

  • parallel (bool, optional) –

    Decides whether grain structure characterisation should be done using parallel execution. Following combinations of options are permitted:

    • If True and char_stage is ‘post_sim’, then grain structyure

    characterisation will be done with parallel computation. * If True and char_stage is ‘in-sim’, then the combination is invalid. The grain characterisaion will be done at the end of each mc iteration. * If False and char_stage is ‘post_sim’, then grain structure characterisation will done after all mc iterations are completed, but one temporal slice after the other. However, the calculation of individual morphological parameters will be done using pooling when possible. When this option is not possible, behaviour will be similar to that of the combination False and ‘in-sim’. * If False and char_stage is ‘in-sim’, then grain structure characterisation will be carried out at the end of each mc iteration. No part of the process will be threaded or pooled or executed in parallel.

    The default is False.

  • find_gbseg (bool, optional) –

    Flag to identify the grain boundary segments. If True, the grain boundary segments will be identified and not if False. GB segments will be identified by UPXO and no other oprtion is needed. The following behaviours should be kept in mind:

    • Will only work if char_grains is True. Assuming it is True,

    the following further points hold. * If find_gbseg is False, but gb_njp_order is True, then, the grain boundary segments will still be identified to allow the calculation of njp order.

    The default is False.

  • g_area (bool, optional) – Flag to calculate grain area. The calculaion takes into consideration, the pixel area of the underlying grid. The default is False.

  • gb_length (bool, optional) –

    Falg to calculate the grain boundary length. The calculation takjes into considertation, side length of the pixel of the underlying grid. The following behaviour should be noted:

    • If char_grains is False, and gb_length is True, then

    grain boundary lengths will not be calculated. * if grain boundary segments have been identified and gb_length is True, then along with calculating grain boundary lengths, the lengths of gerain boundaryu segments will also be calculated.

    The default is False.

  • gb_length_crofton (bool, optional) – Flag to calculate the Crofton perimeter of the grain boundary. For more information, please refer to: https://scikit-image.org/ docs/stable/auto_examples/segmentation/plot_perimeters.html The default is False.

  • gb_njp_order (bool, optional) –

    Flag to calculate the ‘n’ of junction points, that is the value of grain boundary junction point order. Its value is the number of grains a grain boundary junction point is being shared with. If 3, we have a triple point junction, if 4, we have a quadruple point junction and so on. The following behaviours must be noted:

    • Will only be calculated if char_grains is True and grain

    boundary segments have been identified.

    The default is True.

  • g_eq_dia (bool, optional) –

    Flag to calculate the equivalent diameter of the grain. If True, equiavelnt diamater of the grains will be caclculated, not if False. The following behaviours must be noted:

    • If grain_area is False, and g_eq_dia is True, then the

    grain area will still be calculated to allow claculation of grain equivalent diameter. However, only the grain equivalent diameter will be saved as an attribute and not the grain area, which was not requested. * Equiavalent diameter caluclation will consider the area of the pixel in the grid. Infact, it gets carried from the grain_area claculation.

    The default is True.

  • g_feq_dia (bool, optional) – Flag to calculate the Feret equivalent diameter. If True, the Feret equivalent will be calculated, not if False. Behaviours are similar to that of g_eq_dia. The default is True.

  • g_solidity (bool, optional) – Flag to calculate the solidity of grain. The default is True.

  • g_circularity (bool, optional) – Flag to calculate grain circularity. The default is True.

  • g_mjaxis (bool, optional) – Flag to calculate the major axis of the grain. The default is True.

  • g_mnaxis (bool, optional) – Flag to calculate the ninor axis of the grain. The default is True.

  • g_morph_ori (bool, optional) – Flag to calculate the morphological orientation of the grains. Bounded in [-90, 90] degrees. The default is True.

  • g_el (TYPE, optional) – DESCRIPTION. The default is True.

  • g_ecc (bool, optional) – Flag to calculate the eccentricity of the grains. The default is True.

Return type:

None.

set_param_geomrepr(make_mp_grain_centoids=True, make_mp_grain_points=True, make_ring_grain_boundaries=True, make_xtal_grain=True, make_chull_grain=True, create_gbz=True, gbz_thickness=0.1, read_from_file=False, filename=None)[source]

Set parametwers needed to generate geometrical representations of the Monte-Carlo Grain Structure.

Parameters:

  • make_mp_grain_centoids (bool, optional) – Make UPXO multi-point object grom the grain centroids The default is True.

  • make_mp_grain_points (bool, optional) – Make multi-point objects of all pixel cenrtoids in grains. NOTE: Not recommended for large domains. The default is False.

  • make_ring_grain_boundaries (bool, optional) – Make UPXO multi-point object from all points on the grain boundary of a grains. Number of objects made will equal to the number of grains. The default is True.

  • make_xtal_grain (bool, optional) – Make UPXO XTAL object for the grain. The default is True.

  • make_chull_grain (bool, optional) – Flag to create convex hull object of the grain. The default is True.

  • create_gbz (bool, optional) – Flag to create grain boundary zone. This operation will also make the grain core zone. Both of these will be available to be turned into element sets for FE mesh export. The default is True.

  • gbz_thickness (float/int, optional) – Control the thickness of the grain boundary zone. Value must be between 0 and 1 and is the fraction of actual grain boundary thickness in grid units to minor axis length of the grain. NOTE: For grains, where grain boundary zones cannot be created due to morphological restrictions, data for the speciric grain will be kept at None. Default value is 0.1.

Return type:

None.

set_param_mesh(generate_mesh=False, target_fe_software='abaqus', par_treatment='global', mesher='upxo', gb_conformities=('conformal', 'non_conformal'), global_elsizes=(0.5, 1.0), mesh_algos=(4, 6), grain_internal_el_gradient=('constant', 'constant'), grain_internal_el_gradient_par=(('automin', 'automax'), ('automin', 'automax')), target_eltypes=('CSP4', 'CSP8'), elsets=('grains', 'grains'), nsets=('x-', 'x+', 'y-', 'y+'), optimize=(False, False), opt_par=('min_angle', [45, 60], 'jacobian', [0.45, 0.6]), read_from_file=False, filename=None)[source]

Set the meshing parameters for parameter sweep studies

Parameters:

  • generate_mesh (BOOL, optional) – Flag to mesh the grain structure. The default is False.

  • target_fe_software (STR, optional) – The FE software for which the mesh is targetted at. Current options include ‘abaqus’. Future options shall be ‘moose’, ‘damask’ The default is ‘abaqus’.

  • par_treatment (STR, optional) –

    Specifies whether some (see below list) are to apply for all instances in the parameter sweep dataset, OR, whether, a unique parameter is to be used for a unique instance. This applies for the following user input parameters:

    • gb_conformities

    • global_elsizes

    • mesh_algos

    • grain_internal_el_gradient

    • target_eltypes

    • optimize

    If ‘local’, then ‘n’ values for each of the above parameters must be provided. ‘n’ is the number of parameter sweeps, which is len(ps.N). The default is ‘global’.

  • mesher (STR, optional) – Specify the mesher. Options are ‘upxo’, ‘pygmsh’, ‘gmsh’, ‘abaqus’ -‘upxo’: applies only to pizellated mesh (non-conformal) of the 2D, 3D MCGS. -‘pygmsh’, ‘gmsh’: Applies to geometrised 2D MCGS, 3D MCGS, 2D VTGS and 3D VTGS -‘abaqus’: applies to 2D VTGS and geometrised 2D MCGS This will write data to disk. UPXO-ABAQUS python scripts are then to be used to construct and mesh the grain structure in ABAQUS The default is ‘upxo’.

  • gb_conformities (MIXED: STR/ITERABLE, optional) – Individual value options: ‘conformal’, ‘non_conformal’ If STR and ‘conformal’, then all instances will conformally meshed. if STR and ‘non_conformal’, then all instances will non-conformally meshed. if ITERABLE and of the right size, then each instance will be meshed as per the value in the location in gb_conformities corresponding to the instance. if ITERABLE and of the wrong size, parameter sweep study stops. The default is (‘conformal’, ‘non_conformal’).

  • global_elsizes (MIXED: FLOAT/ITERABLE, optional) – If FLOAT, then it will be mapped to all instances If ITERABLE and of the right size, then each instance will be meshed with the corresponding element size. If ITERABLE and of the wrong size, then parameter sweep study stops. The default is (0.5, 1.0).

  • mesh_algos (MIXED: INT/ITERABLE, optional) – If INT, then it will be mapped to all instances If ITERABLE and of the right size, then each instance will be meshed with the corresponding specified algirithm If ITERABLE and of the wrong size, then parameter sweep study will stop. The default is (4, 6).

  • grain_internal_el_gradient (MIXED: STR/ITERABLE, optional) – If STR, then all instances will be meshed with the same element gradient specification If ITERABLE and of the right size, then all instances will be meshed using correpsoning values of element gradients If ITERABLE and of the wrong size, then parameter sweep study stops. Options are ‘constant’, ‘linear_gb_to_centroid’, ‘linear_centroid_to_gb’, ‘linear_gb_to_core’, ‘linear_core_to_gb’ - For value other than ‘constant’, then global_elsizes will not be used. Instead values provided by grain_internal_el_gradient_par will be used. - For value ‘linear_gb_to_centroid’, min size will be near gb and max size will be at centroid. Variation will be linear. - For value ‘linear_centroid_to_gb’, max size will be near gb and min size will be at centroid. Variation will be linear. - For value ‘linear_gb_to_core’, min size will be near gb and size increases linearly towards the max size along vectors normal to the local gb edge. Vector will be directed towards inner region of the grain. - For value ‘linear_core_to_gb’, max size will be near gb and size decreases linearly towards the min size along vectors normal to the local gb edge. Vector will be directed towards inner region of the grain The default is (‘constant’, ‘constant’).

  • grain_internal_el_gradient_par (MIXED: ITERABLE(STR/FLOAT)/ITERABLE,)

  • optional. – If STR/FLOAT, same action will be mapped onto all instances. If (STR, STR), only allowed non-interchangeable values is ‘automin’ and ‘automax’. If (‘automin’, ‘automax’), then element sizes will be calculated using a combination of grain boundary properties, maximum intercept along the curve normal, grain shape factor, etc. The procedure is described in theoretical manual. If (FLOAT, FLOAT), then values will be chosen accordingly and maps accordingly to all instances. NOTE @ dev: RETAIN THIS TO BE (‘automin’, ‘automax’) and not replace with just ‘auto’, for reason of conformity to a standard user data specification format. The default is ((‘automin’, ‘automax’),).

  • target_eltypes (MIXED: STR/ITERABLE, optional) – If STR, value is correct and allowed, then same element types will be mapped to all instances. If ITERABLE, all values are STR, correct and allowed, then values get mapped to each instance seperately and accordingly. The default is (‘CSP4’, ‘CSP8’).

  • elsets (MIXED: STR/ITERABLE, optional) – If STR, valid and allowed, the resuested elment set will be mapped to all instances. If ITERABLE, values are STR, valid and allowed, then values will be mapped to corresponding instances. The default is (‘grains’, ‘grains’).

  • nsets (ITERABLE, optional) – Nodal sets to make. Used to impose boundary conditions. Options: ‘x-’, ‘x+’, ‘y-’, ‘y+’, ‘gb’, ‘rp_random_none_10’ - Option ‘gb’: grain boundary nodes. A ‘gn’ nodal set will be created for each grain. Naming will be based on parent grain name. - Option ‘rp_random_10’: representative points, 10 in number. These points are points fully inside the grain. None of these points would lie on the grain boundary of the grain. ‘random’ denotes random positioning of representative points. Following ‘none’ indicates completely randomised. If in place of ‘none’, we have a number (INT/FLOAT), then this number specifies the minimum distance of seperation between all representative points inside the grain. The following number 10, necessiates that there should be 10 coordinate positions (as ITERABLES), if ‘random’ locationing. If these input data-format rules are not conformed to, then parameter sweep study stops. The default is (‘x-’, ‘x+’, ‘y-’, ‘y+’, ).

  • optimize (MIXED: BOOL/ITERABLE, optional) – If BOOL, then this optimization flag will be mapped to all instances. If ITERABLE and of right size, then each optimization flag will be mapped to each instance accordingly. If ITERABLE and of wrong size, then parameter sweep study will stop. Options: True, False The default is (False, False).

  • opt_par (MIXED: STR/ITERABLE, optional) – Specifies the element quality metric to optimize the mesh for. The default is (‘min_angle’, [40, 60], ‘jacobian’, [0.45, 0.6]) ‘min_angle’ is the minimum angle in the distribution of minimum angles of all finite elements. [40, 60] denotes the bounds of acceptance. Note that if objectives are not met, UPXO will enable recursive mesh refinement near places where these minimum angle falls outside the specified bounds. ‘jacobian’: similar explanations apply.

Return type:

None.

save()[source]

Pickle the dataset

update_gmp()[source]

Set or update te gmp.

update_qmp()[source]

Set or update te qmp.

plot(defaults=False, docformat='pdf', xax='time', yax='area', zax='sim', xaxpar='', yaxpar='', zaxpar='', plot_type='best')[source]
if defaults=True:

It generates a set of plots to enable getting a quick overview of the data. Plots will be exported to a PDF [ref 1].

Following plots are made.

  • Grain structure plots of the final MC step of all sims.

  • Grain size evolution for all sims.

[ref 1]: Currently, only PDF is supported. It is planned to enable writing data to MS Word, MS PPT, Google Doc, Google presentation, MS Excel and Google Spreadsheet.

yax: y-axis

Options: time, {morph. parameter}

zax: z-axis

Options:

xaxpar: Parameter for the x-axis yaxpar: Parameter for the y-axis zaxpar: Parameter for the z-axis .. note:

if all in (xaxpar, yaxpar, zaxpar) is provided,
UPXO will override xax, yax, zax

plot_type: Type of visualization

property uigrid

This is an imitation method. It imitates the instantiated class which makes uigrid attribute. Imitation is of the 1st grain structure instance. The reason for making an imitation is:

  • All grain structure instances WILL have grids having the

same dimensionality, bounds and increments. * Hence, it is not needed to make a seperate grid availabale to the paramater sweep object. * Instead, when this property method is called, it just returns the uigrid of the first grain structure isntance, if it exists. * No big deal here.

NOTE: This documentation applies also to uisim, uigsc, uimesh, uigeomrepr

property uisim

This is an imitation method. Refer to ps.uigrid for more documentation.

property uigsc

This is an imitation method. Refer to ps.uigrid for more documentation.

property uimesh

This is an imitation method. Refer to ps.uigrid for more documentation.

property uigeomrepr

This is an imitation method. Refer to ps.uigrid for more documentation.

info_attributes(n, throw=False)[source]

Info attributes.

generate_report(docformat='pdf')[source]
Parameters:

docformat (TYPE, optional) – DESCRIPTION. The default is ‘pdf’.

Return type:

None.

N
nstates
domain
dim
algo_hop
algo_hops
purge_previous
gsi
gmp
qmp
mesh_instances
to_excel()[source]

Export or convert to excel.

model()[source]

Model.

property default_mcalg

Default mcalg.