Surrogate-assisted Bayesian validation of computational models

BayesValidRox is an open-source python package that provides methods for surrogate modeling, Bayesian inference and model comparison.

Weighting model results against data with associated uncertainty, costs and sparsity

An introductory tutorial to the overall workflow with bayesvalidrox is provided in TUTORIAL and descriptions of the available examples can be found in EXAMPLES. The functionality and options for the different classes is described more in-depth in USER GUIDE and a list of all the classes and functions is provided in API.

Installation

This package runs under Python 3.9 for versions <1.0.0 and 3.9+ from version 1.0.0 on, use pip to install:

pip install bayesvalidrox

Quickstart

Here we show a minimal example to get started on working with BayesValidRox. The USER GUIDE goes into more detail on the available options and proposed workflow.

The central functionalities of BayesValidRox all depend on building an object of class Engine that includes an interface to a model and a definition of an input space and sampling option in the form of an ExpDesigns object. It can contain and build a surrogate model of class MetaModel, but also functions without one.

We import the needed classes in our main file main.py.

>>> from bayesvalidrox import PyLinkForwardModel, InputSpace, ExpDesigns, Engine, MetaModel

Here we use a simple linear model. This is defined in another python file in the same folder, here we call it model.py. This file contains a python function that expects samples of two parameter and returns a linear combination of them. For a detailed description of the expected output format see Models.

>>> def model(samples):
>>> return {'Z':samples[:,0]+2*samples[:,1], 'x_values':[0]}

With this we can create the interface to the model in main.py.

>>> model = PyLinkForwardModel()
>>> model.link_type = 'Function'
>>> model.py_file = 'model'
>>> model.name = 'linear model'
>>> model.Output.names = ['Z']

We specify marginal distributions on the inputs in an object of class InputSpace and use this to build the experimental design.

>>> inputs = InputSpace()
>>> inputs.add_Marginals()
>>> inputs.Marginals[0].name = 'input0'
>>> inputs.Marginals[0].dist_type = 'unif'
>>> inputs.Marginals[0].parameters = [0,1]
>>> inputs.add_Marginals()
>>> inputs.Marginals[1].name = 'input1'
>>> inputs.Marginals[1].dist_type = 'unif'
>>> inputs.Marginals[1].parameters = [0,1]
>>> expdes = ExpDesigns(inputs)
>>> expdes.sampling_method = 'random'

If we do not want to build a surrogate model, we can define the engine from these objects.

>>> engine = Engine(None, model, expdes)

If we want to build a surrogate model, we create and object of class MetaModel and set its properties. Here we build an arbitrary Polynomial Chaos Expansion and train it on samples given by the experimental design and the model.

>>> metamodel = MetaModel(Inputs)
>>> metamodel.meta_model_type = 'aPCE'
>>> metamodel.pce_reg_method = 'FastARD'
>>> metamodel.pce_deg = 3
>>> MetaMod.pce_q_norm = 0.85
>>> expdes.n_init_samples = 10
>>> engine = Engine(metamodel, model, expdes)
>>> engine.start_engine()
>>> engine.train_normal()

The engine with the trained metamodel can now be used for postprocessing, Bayesian inference, of Bayesian model comparison.

License

BayesValidRox is licensed under the MIT license.

Contribution

We would be happy for you to contribute to BayesValidRox. This can include e.g. reporting issues, proposing new features, working on features, or support with the documentation. If you want to contibute, check out our contribution guidelines. You can contact us on the gitlab page.

Further contents

Indices and tables