model

Created on 23 dec. 2010

Code author: jhkwakkel <j.h.kwakkel (at) tudelft (dot) nl>

ModelStructureInterface

class model.ModelStructureInterface(workingDirectory, name)

Bases: object

ModelStructureInterface is one of the the two main classes used for performing EMA. This class should be extended to provide an interface to the actual model.

uncertainties

list of uncertainty instances

outcomes

list of outcome instances

name

name of the model interface

output

results, this should be a dict with the names of the outcomes as key

__init__(workingDirectory, name)

interface to the model

Parameters:

• workingDirectory – workingDirectory for the model.
• name – name of the modelInterface. The name should contain only alphanumerical characters.

model_init(policy, kwargs)

Method called to initialize the model.

Parameters:

• policy – policy to be run.
• kwargs – keyword arguments to be used by model_intit. This gives users to the ability to pass any additional arguments.

Note

This method should always be implemented. Although in simple cases, a simple pass can suffice.

run_model(case)

Method for running an instantiated model structure.

This method should always be implemented.

Parameters:case – keyword arguments for running the model. The case is a dict with the names of the uncertainties as key, and the values to which to set these uncertainties.

Note

This method should always be implemented.

retrieve_output()

Method for retrieving output after a model run.

Returns:the results of a model run.

reset_model()

Method for reseting the model to its initial state. The default implementation only sets the outputs to an empty dict.

cleanup()

This model is called after finishing all the experiments, but just prior to returning the results. This method gives a hook for doing any cleanup, such as closing applications.

In case of running in parallel, this method is called during the cleanup of the pool, just prior to removing the temporary directories.

get_model_uncertainties()

Method for retrieving model structure uncertainties.

Returns:list of the uncertainties of the model interface.

set_working_directory(wd)

Method for setting the working directory of the model interface. This method is used in case of running models in parallel. In this case, each worker process will have its own working directory, to avoid having to share files across processes. This requires the need to update the working directory to the new working directory.

Parameters:wd – The new working directory.

SimpleModelEnsemble

class model.SimpleModelEnsemble(sampler=<samplers.LHSSampler object at 0x09795370>)

Bases: object

One of the two main classes for performing EMA. The ensemble class is responsible for running experiments on one or more model structures across one or more policies, and returning the results.

The sampling is delegated to a sampler instance. The storing or results is delegated to a callback instance

the class has an attribute ‘parallel’ that specifies whether the experiments are to be run in parallel or not. By default, ‘parallel’ is False.

an illustration of use

>>> model = UserSpecifiedModelInterface(r'working directory', 'name')
>>> ensemble = SimpleModelEnsemble()
>>> ensemble.set_model_structure(model)
>>> ensemble.parallel = True #parallel processing is turned on
>>> results = ensemble.perform_experiments(1000) #perform 1000 experiments

In this example, a 1000 experiments will be carried out in parallel on the user specified model interface. The uncertainties are retrieved from model.uncertainties and the outcomes are assumed to be specified in model.outcomes.

__init__(sampler=<samplers.LHSSampler object at 0x09795370>)

Class responsible for running experiments on diverse model structures and storing the results.

Parameters:sampler – the sampler to be used for generating experiments. By default, the sampling technique is LHSSampler.

perform_experiments(cases, callback=<class 'util.DefaultCallback'>, kwargs=None)

Method responsible for running the experiments on a structure. In case of multiple model structures, the outcomes are set to the intersection of the sets of outcomes of the various models.

Parameters:

• cases – In case of Latin Hypercube sampling and Monte Carlo sampling, cases specifies the number of cases to generate. In case of Full Factorial sampling, cases specifies the resolution to use for sampling continuous uncertainties. Alternatively, one can supply a list of dicts, where each dicts contains a case. That is, an uncertainty name as key, and its value.
• callback – Class that will be called after finishing a single experiment,
• kwargs – generic keyword arguments to pass to the model_init

Returns:

a structured numpy array containing the experiments, and a dict with the names of the outcomes as keys and an numpy array as value.

suggested use

In general, analysis scripts require both the structured array of the experiments and the dictionary of arrays containing the results. The recommended use is the following:

>>> results = ensemble.perform_experiments(10000) #recommended use
>>> experiments, output = ensemble.perform_experiments(10000) #will work fine

The latter option will work fine, but most analysis scripts require to wrap it up into a tuple again:

>>> data = (experiments, output)

Another reason for the recommended use is that you can save this tuple directly:

>>> import expWorkbench.util as util
>>> util.save_results(results, file)

add_policy(policy)

Add a policy.

Parameters:policy – policy to be added, policy should be a dict with at least a name.

add_policies(policies)

Add policies, policies should be a collection of policies.

Parameters:policies – policies to be added, every policy should be a dict with at least a name.

set_model_structure(modelStructure)

Set the model structure. This function wraps the model structure in a tuple, limiting the number of model structures to 1.

Parameters:modelStructure – a ModelStructureInterface instance.

add_model_structure(ms)

Add a model structure to the list of model structures.

Parameters:ms – a ModelStructureInterface instance.

add_model_structures(mss)

add a collection of model structures to the list of model structures.

Parameters:mss – a collection of ModelStructureInterface instances

_generate_cases(nrOfCases)

number of cases specifies the number of cases to generate in case of Monte Carlo and Latin Hypercube sampling.

In case of full factorial sampling it specifies the resolution on non categorical uncertainties.

In case of multiple model structures, the uncertainties over which to explore is the intersection of the sets of uncertainties of the model interface instances.

Parameters:nrOfCases – In case of Latin Hypercube sampling and Monte Carlo sampling, nrOfCases specifies the number of cases to generate. In case of Full Factorial sampling, nrOfCases specifies the resolution to use for sampling continuous uncertainties.