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.
- func – Function that evaluates a matmodlab simulation. Must have signature
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()