2.5. Permutator

Todo

clean up the description to be more clear what func is (a function that runs a simulation)

It is useful to investiage sensitivities of models to model inputs. Permutating values of model inputs involves running jobs with different realization of parameters. Ideal for investigating model sensitivities. A permutator instance is created through the Permutator constructor. Minimally, the constructor requires a function to evaluate func, initial parameters xinit, and a runid.

permutator = Permutator(func, xinit, runid)

func is called as func(x, *args) where x are the current values of the permutated variables and args contains in its last component:

dirname = args[-1]

where dirname is the directory where simulations should is to be run.

Permutator Constructor

The formal parameters to Permutator are

class Permutator(func, xinit, runid, method="zip", correlations=False, verbosity=1, descriptor=None, nprocs=1, funcargs=None, d=None)

Create a Permutator object

Parameters:
  • func – Function that evaluates a matmodlab simulation. Must have signature func(x, *args), where x are the current values of the permutated variable and funcargs are described below.
  • xinit (List of PermutateVariable objects) – Initial values of simulation parameters.
  • runid (str) – runid for the parent Permutation process.
  • method (str) – The method for determining how to combine parameter values. One of zip or combine. The zip method runs one job for each set of parameters (and, thus, the number of realizations for each parameter must be identical), the combine method runs every combination of parameters.
  • correlations (bool) – Create correlation table and plots of relating permutated parameters and return value of func [default: False].
  • descriptor (int of None) – Descriptors of return values from func
  • nprocs – Number of simultaneous jobs [default: None]
  • funcargs (list or None) – Additional arguments to be sent to func. The directory of the current job is appended to the end of funcargs. If None,
  • d (str or None) – Parent directory to run jobs. If the directory does not exist, it will be created. If not given, the current directory will be used.

Each Permutator job creates a directory runid.eval with the following contents:

ls runid.eval
eval_000/    eval_002/    mml-evaldb.xml
eval_001/    ...          runid.log

The eval_... directory holds the output of the ith job and a params.in file with the values of each permutated parameter for that job. mml-evaldb.xml contains a summary of each job run. mml view recognizes mml-evaldb.xml files.

Run a permutation job by invoking the Permutator.run() method.

PermutateVariable Factory Method

The formal parameters to PermutateVariable are

PermutateVariable(name, init, method="list", b=None, N=10)

Create a PermutateVariable object

Parameters:
  • name (str) – Name of variable
  • init (float or list) – Initial value or values, dependending on method.
  • method (str) – Method used to generate all values. If list, than all values shall be given in init. Otherwise, values will be generated. Valid methods are list, weibull, uniform, normal, percentage.
  • b (float) – For methods other than list, values are generated from a function called as fun(init, b, N). The meaning of b is dependent on which method fun represents.
  • N (int) – For methods other than list, the number of values to generate

Examples

The following input stub demonstrates how to permutate the K parameter

K = PermutateVariable("K", [75, 125, 155])
K = PermutateVariable("K", 125, method="weibull", b=14)
K = PermutateVariable("K", 125, method="percentage", b=10, N=10)

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.

from matmodlab import *

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

    mps = MaterialPointSimulator(runid)
    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)

def runjob():
    N = 15
    K = PermutateVariable('K', 125e9, method='weibull', b=14, N=N)
    G = PermutateVariable('G', 45e9, method='percentage', b=10, N=N)
    xinit = [K, G]
    permutator = Permutator('permutation', func, xinit, method='zip',
                            descriptors=['MAX_PRES'], correlations=True)
    permutator.run()

runjob()