2.6. Permutator¶

Overview¶

It is useful to investiage sensitivities of models to model inputs. The Permutator runs jobs with different realization of parameters. The Permutator is designed as a tool for discovering and investigating model sensitivities.

The Permutator Constructor¶

class Permutator(job, func, xinit, method=ZIP, correlations=False, verbosity=None, descriptors=None, nprocs=1, funcargs=[], d=None, shotgun=False, bu=False)¶

Create a Permutator object and set up the simulation.

The job string is the simulation ID. The Permutator creates a job.eval/ directory in the simulation directory. The ith individual job is then run in job.eval/eval_i/.

The Permutator writes relevant simulation information to job.eval/job.xml. The Matmodlab.Visualizer can read the job.xml file and display the permutated job.

func is a function that evaluates a Matmodlab simulation. It is called as func(x, xnames, d, job, *funcargs), where x are the current values of the permutated variables, xnames are their names, d is the simulation directory of the current job, job is the job ID, and funcargs are additional arguments to be sent to func.

xinit is a list of initial values of the simulation parameters to be permutated. Each member of the list must be a PermutateVariable instance.

The following arguments are optional

method is the method for determining how to combine parameter values. One of ZIP or COMBINATION. The ZIP method runs one job for each set of parameters (and, thus, the number of realizations for each parameter must be identical), the COMBINATION method runs every combination of parameters.

correlations is a boolean that, if True, instructs the Permutator to create a correlation table and plots relating permutated parameters and return value of func.

descriptors is a list of descriptors for the values returned from func.

nprocs is the integer number of simultaneous jobs to run.

d is the parent directory to run jobs. If the directory does not exist, it will be created. If the directory exists and bu is False, the directory will be first erased and then re-created. If the directory exists but bu is True, the directory is archived.

If shotgun is True, input parameters are randomized.

Running the Permutator¶

Permutator.run()¶: Run the simulation

PermutateVariable Factory Method¶

PermutateVariable(name, init, method=LIST, b=None, N=10)¶

Create a PermutateVariable object

name is the name of variable and init is its initial value (or values). method is the method use to generate all values. If method is LIST, then all values shall be given in init. Otherwise, values will be generated. Valid methods are LIST, WEIBULL, UNIFORM, NORMAL, PERCENTAGE.

The interpretation of the following arguments depends on method

For methods other than LIST, values are generated from a function called as fun(init, b, N). The interpretation of b is dependent on which method fun represents. N is the number of values to generate.

Example¶

The following input demonstrates how to permutate the K and G parameters to the elastic model. The input can be found in matmodlab/examples/permutate.py.

The Example Script¶

from matmodlab import *

def func(x, xnames, d, job, *args):

    mps = MaterialPointSimulator(job)
    mps.StrainStep(components=(1, 0, 0), increment=1., scale=-.5, frames=10)
    mps.StrainStep(components=(2, 0, 0), increment=1., scale=-.5, frames=10)
    mps.StrainStep(components=(1, 0, 0), increment=1., scale=-.5, frames=10)
    mps.StrainStep(components=(0, 0, 0), increment=1., scale=-.5, frames=10)

    # set up the material
    parameters = dict(zip(xnames, x))
    mps.Material('elastic', parameters)

    # set up and run the model
    mps.run()

    s = mps.get('STRESS_XX')
    return np.amax(s)

K = PermutateVariable('K', 125e9, method=WEIBULL, b=14, N=15)
G = PermutateVariable('G', 45e9, method=PERCENTAGE, b=10, N=15)
permutator = Permutator('permutation', func, [K, G], method=ZIP,
                        descriptors=['MAX_PRES'], correlations=True)
permutator.run()

How Does the Script Work?¶

This section describes each part of the example script

from matmodlab import *

This statement makes the Matmodlab objects accessible to the script.

K = PermutateVariable('K', 125e9, method=WEIBULL, b=14, N=15)
G = PermutateVariable('G', 45e9, method=PERCENTAGE, b=10, N=15)

These statements define parameters K and G to be permutated by the WEIBULL method with a Weibull modulus of 14 (b) and PERCENTAGE method with parameters chosen between +/- 10% of the initial (b), respectively.

permutator = Permutator('permutation', func, [K, G], method=ZIP,
                        descriptors=['MAX_PRES'], correlations=True)

This statement instantiates the Permutator object, using the ZIP method. Correlations between K, G and the output variable MAX_PRES are requested. Note that MAX_PRES is returned by func and not Matmodlab.

permutator.run()

This statement runs the job.

def func(x, xnames, d, job, *args):

    mps = MaterialPointSimulator(job)
    mps.StrainStep(components=(1, 0, 0), increment=1., scale=-.5, frames=10)
    mps.StrainStep(components=(2, 0, 0), increment=1., scale=-.5, frames=10)
    mps.StrainStep(components=(1, 0, 0), increment=1., scale=-.5, frames=10)
    mps.StrainStep(components=(0, 0, 0), increment=1., scale=-.5, frames=10)

    # set up the material
    parameters = dict(zip(xnames, x))

These statements define the function exercised by the Permutator. The first lines are the instantiation of the MaterialPointSimulator, and specification of the analysis steps. In the last line, the parameters dictionary is assembled with the current values of the permutated variables in x and their names xnames.

mps.Material('elastic', parameters)

# set up and run the model
mps.run()

These statements set up the simulators material and run the job.

s = mps.get('STRESS_XX')
return np.amax(s)

These statements get the maximum axial stress from the simulation and return it.