UQ[PY]LAB USER MANUAL

THE MODEL MODULE

C. Lataniotis, S. Marelli, B. Sudret

CHAIR OF RISK, SAFETY AND UNCERTAINTY QUANTIFICATION

STEFANO-FRANSCINI-PLATZ 5

CH-8093 Z

URICH

Risk, Safety &

Uncertainty Quantification

How to cite UQ[PY]LAB

C. Lataniotis, S. Marelli, B. Sudret, Uncertainty Quantiﬁcation in the cloud with UQCloud Proceedings of the 4th

International Conference on Uncertainty Quantiﬁcation in Computational Sciences and Engineering (UNCECOMP

2021), Athens, Greece, June 27–30, 2021.

How to cite this manual

C. Lataniotis, S. Marelli, B. Sudret, UQ[py]Lab user manual – The Model module, Report # UQ[py]Lab -V0.9-103,

Chair of Risk, Safety and Uncertainty Quantiﬁcation, ETH Zurich, Switzerland, 2023

BIBT

X entry

@TechReport{UQdoc_09_103,

author = {Lataniotis, C. and Marelli, S. and Sudret, B.},

title = {{UQ[py]Lab user manual -- The Model module }},

institution = {Chair of Risk, Safety and Uncertainty Quantification, ETH Zurich,

Switzerland},

year = {2023},

note = {Report \# UQ[py]Lab -V0.9-103}

}

List of contributors:

Name Contribution

A. Giannoukou, A. Hlobilov

a Translation from the UQLab manual

Document Data Sheet

Document Ref. UQ[PY]LAB-V0.9-103

Title: UQ[PY]LAB user manual – The Model module

Authors: C. Lataniotis, S. Marelli, B. Sudret

Chair of Risk, Safety and Uncertainty Quantiﬁcation, ETH Zurich,

Switzerland

Date: 07/06/2023

Doc. Version Date Comments

V0.8 01/07/2022 Initial release

V0.9 07/06/2023 UQ[PY]LAB V0.95 release

Abstract

Computational models are used nowadays in most ﬁelds of natural-, social sciences and

engineering. The purpose of the UQLab platform and its derivatives (UQCloud, UQ[py]Lab,

etc.) is to quantify the impact of uncertainties in the model parameters onto the predictions

of such models. In this manual, we describe how to deﬁne such a computational model in the

UQ[PY]LAB platform.

Models can be as simple as a single line function described as a string or a Python script.

Third-party codes can be used by wrapping them up into a Python script. Surrogate models

(see, e.g., UQ[PY]LAB User Manual – Polynomial Chaos Expansions and UQ[PY]LAB User

Manual – Kriging (Gaussian process modelling)) can be built and used later on as any other

models.

The manual consists of three sections, namely a short description of the concept of computa-

tional models, a section on usage comprising commented examples and a reference list.

Keywords: UQ[PY]LAB, Computational Models, MODEL Module

Contents

1 Theory 1

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Formalism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.3 Model examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4 Client-side and server-side computational models . . . . . . . . . . . . . . . . 3

2 Usage 5

2.1 Initialization of the workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2 Client-side computational models . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2.1 Creating a model from an existing Python ﬁle . . . . . . . . . . . . . 6

2.2.2 Creating wrappers/plugins to third party software . . . . . . . . . . . 8

2.2.3 Understanding wrappers . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.2.4 Creating a UQ[PY]LAB MODEL plugin . . . . . . . . . . . . . . . . . . . 9

2.3 Cloud-side computational models . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.4 Models with multiple outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Reference List 11

3.1 Create a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2 Evaluate a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 1

Theory

1.1 Introduction

According to the general framework of uncertainty quantiﬁcation introduced in Sudret (2007);

de Rocquigny et al. (2008), a computational model can refer to a physical system, a set of

assessment criteria or any other kind of workﬂow that propagates a set of input parameters

to a set of output quantities of interest (Figure 1).

Step A

Model(s) of the system

Assessment criteria

Step B

Quantiﬁcation of

sources of uncertainty

Step C

Uncertainty propagation

Random variables

Computational model

Moments

Probability of failure

Response PDF

Step C’

Sensitivity analysis

Bayesian inversion

Figure 1: Visual representation of the global theoretical framework for uncertainty quantiﬁ-

cation developed by Sudret (2007); de Rocquigny et al. (2008), which gives the theoretical

foundations to the UQLab software and its derivatives (UQCloud, UQ[py]Lab, etc.)

This guide provides an in-depth manual on how to connect various types of computational

models to the UQ[PY]LAB software framework.

1.2 Formalism

The physical model can be seen as a black-box, i.e., as a map from the space of input param-

eters to that of output quantities:

Y = M(X) (1.1)

UQ[PY]LAB user manual

where X is a random vector that parametrizes the variability of the input parameters (typ-

ically through a joint probability density function (PDF)), and Y is the vector of model

responses. The computational model can be deterministic in the sense that evaluating it

repeatedly for a given input realization x

will always give the same result y

= M(x

However, the uncertainty in the input variables causes Y to be a random variable/vector as

well. Indeed, one of the main applications of uncertainty quantiﬁcation is that of propagating

the randomness in the inputs X to the outputs Y . Commonly used models in advanced ap-

plications often comprise both random and deterministic parameters. When this is the case,

the following notation is introduced to clarify such distinction:

Y = M(X, P ) (1.2)

where P is a set of deterministic parameters that are used to properly conﬁgure a model (e.g.

conﬁguration options, ﬁxed values for parametric functions, etc.).

1.3 Model examples

As introduced in Section 1.1 a model is a rather abstract concept. In the following a short

overview of some of the most common model families in uncertainty quantiﬁcation is given:

• Analytic functions. Any function of the form y = f (x) can be considered as a compu-

tational model. Mathematical functions are normally known in their closed-forms and

they are often used during the development of new algorithms as well-known bench-

marks.

• Numerical models. The vast majority of physical phenomena cannot be approximated

by simple closed-form equations. Advanced discretization techniques (e.g., ﬁnite dif-

ference or ﬁnite element schemes) are often used to solve ordinary (resp. partial)

differential equations that model the system, and to calculate the model response. This

type of models can be very demanding computationally.

• Wrappers to third-party codes. Sometimes complex simulations (e.g. multiphysics mod-

els) rely on the execution of codes that require third party software. The input-output

structure of such software may be signiﬁcantly different than that in UQ[PY]LAB.

Wrappers are small Python scripts that “translate” the input-output format of a third

party code to and from the input-output format of UQ[PY]LAB.

• Workﬂows. In many industrial applications complex models require composite work-

ﬂows for proper execution. Such workﬂows can comprise of several wrappers between

different third-party codes, access to storage devices, execution of batch scripts etc. A

workﬂow is a generalization of the concept of wrapper to the general working environ-

ment.

UQ[PY]LAB-V0.9-103 - 2 -

The Model module

The UQ[PY]LAB MODEL module offers a convenient tool to include the ﬁrst three types of

models (functions, numerical models and wrappers) in an uncertainty quantiﬁcation analysis.

1.4 Client-side and server-side computational models

UQ[PY]LAB offers two possibilities when it comes to choosing the host computer that evalu-

ates a computational model:

• Client-side: This refers to the most common usage scenarios as presented in Section

1.3. The computational model is a Python script that is evaluated on the client com-

puter. Such a Python script can entail any kind of computational model ranging from

simple analytical functions to wrappers to third-party software and complex workﬂows.

• Cloud-side: In the case when simple models are used (mainly low computational cost

analytical functions), they can be hosted and evaluated on the cloud. Using cloud-based

models alleviates the communication overhead that a client-based solution would incur.

UQ[PY]LAB-V0.9-103 - 3 -

Chapter 2

Usage

2.1 Initialization of the workspace

The instructions and commands that are provided in this usage guide assume that certain

initialization steps have already been taken by the user within their Python environments

(Spyder, Jupiter notebooks, etc.). These steps are covered next.

First import the sessions module from the uqpylab package, as well as numpy:

from uqpylab import sessions

import numpy as np

Start a UQCloud session:

mySession = sessions.cloud(host=UQCloudhost, token=UQCloudtoken)

where UQCloudhost is a string that contains the URL of a UQCloud API service endpoint

and UQCloudtoken is a string that authenticates the user. Both are user-speciﬁc and are

provided after successful registration in the UQ[py]Lab website.

Finally, assign the command line interface of the session to a short variable for convenience:

uq = mySession.cli

The last command is not necessary, but it is fully adopted in the manual for convenience

(shorter expressions), and also for familiarity to users that have already used UQLAB.

2.2 Client-side computational models

In this section the Ishigami function, a commonly used benchmark in sensitivity analysis is

chosen to showcase the available options to create client-side models in UQ[PY]LAB:

f(x) = sin(x

) + a sin

) + b x

sin(x

) (2.1)

where a = 7 and b = 0.1 are scalar values. The input vector X comprises 3 components

uniformly distributed in the interval X

∼ U (−π, π).

UQ[PY]LAB user manual

2.2.1 Creating a model from an existing Python ﬁle

To use a python ﬁle as our computational model, we need to:

• create a Python script that implements the Ishigami function;

• create a UQ[PY]LAB model object based on it;

• use the created object to calculate model responses.

First, we create the ﬁle ishigami.py in a directory that belongs to the Python module

search path. To deﬁne the function, we simply translate Eq. (2.1) in Python syntax as

follows:

import numpy as np

def model(X):

X = np.array(X,ndmin=2)

return np.sin(X[:,0]) + 7

np.power(np.sin(X[:,1]),2) +

0.1

np.power(X[:,2],4)

np.sin(X[:,0])

Note that the function is vectorized, i.e., it allows for the evaluation of N different realiza-

tions X =



(1)

, . . . , x

(N)



, x

(i)

∈ R

in a single call. Within UQ[PY]LAB the standard

convention is used to represent X as a multi-dimensional matrix X of dimension N × M:

X.shape = (N, M) # X is a numpy array

It is recommended to include the command X= np.array(X, ndmin=2), which ensures

that X will be correctly interpreted in special cases (e.g., a single sample of X with M > 1).

Each row i of the X matrix corresponds to a realization x

(i)

, while each column j corresponds

to the j-th component of each vector x

(i)

, or X(i, j) = x

(i)

. The output matrix of model

responses Y has the same format, i.e., Y(i,j) = y

(i)

. Therefore, in the case of the scalar-

valued Ishigami function, Y.shape = (N, 1).

A MODEL object can be created in UQ[PY]LAB from the just created function as follows:

# Define the model options

modelopts = {

"Type" : "Model",

"ModelFun" : "ishigami.model"

}

# Create the model

myModel = uq.createModel(modelopts)

A matrix of inputs can be speciﬁed as follows:

X = np.array([[1,2,3], [4,5,6]])

The uq.evalModel command can be used to directly evaluate the model response on the

speciﬁed matrix of inputs X:

Y = uq.evalModel(myModel, X)

UQ[PY]LAB-V0.9-103 - 6 -

The Model module

Vectorization

The default behaviour of UQ[PY]LAB is to assume that models speciﬁed in external ﬁles

are vectorized. However, it is possible to specify that the provided function is not vector-

ized, so that UQ[PY]LAB calculates the model responses iteratively on one row of the input

matrix X at a time. Consider the following ﬁle ishigami_nonVec.py that implements a

non-vectorized version of the Ishigami function:

import numpy as np

def model(X):

return np.sin(X[0])+7

np.power(np.sin(X[1]),2)+

0.1

np.power(X[2],4)

np.sin(X[0])

Then, the following syntax enables non-vectorized model evaluations in UQ[PY]LAB:

# Define the model options

modelopts = {

"Type" : "Model",

"ModelFun" : "ishigami_nonVec.model",

"isVectorized" : 0

}

# Create the model

myModel = uq.createModel(modelopts)

Note that the performance of non-vectorized functions is in general greatly reduced (some-

times by orders of magnitude) w.r.t. their vectorized counterparts.

Passing parameters to a model

In many cases model functions depend on additional non-random parameters, e.g., con-

stant values, ﬂags or even conﬁguration ﬁles. It is possible to include non-random parameters

in a MODEL object with the Parameters dictionary.

A parametric function in UQ[PY]LAB is a function with two input parameters of the form

Y = myFunction(X, P), where P is a dictionary of parameters. As an example, a parametric

(and vectorized) version of the Ishigami function ishigami_parametric.py could read as

follows:

import numpy as np

def model(X, P):

X = np.array(X, ndmin=2)

return np.sin(X[:, 0]) + P['a']

np.power(np.sin(X[:, 1]), 2) +

P['b']

np.power(X[:,2], 4)

np.sin(X[:, 0])

To set the parameters to the same values as in the previous examples (a = 7, b = 0.1), the

following code can be used:

# Define the model options

modelopts = {

"Type" : "Model",

"ModelFun" : "ishigami_parametric.model",

"Parameters" : {

"a" : 7,

"b" : 0.1

UQ[PY]LAB-V0.9-103 - 7 -

UQ[PY]LAB user manual

}

# Create the model

myModel = uq.createModel(modelopts)

2.2.2 Creating wrappers/plugins to third party software

There are several ways to connect external sofware to a UQ[PY]LAB workﬂow. These include

special plugins (e.g., Abaqus Python package), interfaces to different languages, shell/sys-

tem integration (e.g., Python os.system command) and many others. In this section the

guidelines on how to write wrapper codes/plugins that can be used by UQ[PY]LAB’s built-in

MODEL module are presented.

2.2.3 Understanding wrappers

A code wrapper, also known as a plug-in, is a code that allows the execution of one program

within the scope of another. To some degree, it can be seen as a “translator” from the ﬁrst

program to the second. Therefore, four main points are needed to create a wrapper suitable

for UQ[PY]LAB:

• The input format of the software that is to be connected to UQ[PY]LAB: Most high

level modelling software use as input parameters human-readable conﬁguration ﬁles

as well as a command line to be executed.

• The output format of the software that is to be connected to UQ[PY]LAB: af-

ter the computation is ﬁnished, the results are normally saved into output ﬁles with

pre-determined format. Depending on the software, they may be plain text or binary

(sometimes even in proprietary format) ﬁles, or in rare cases even simple text output

printed directly on screen.

• The input/output format of the UQ[PY]LAB modelling interface: thanks to its

black-box-centric design, UQ[PY]LAB expects wrappers to external software to behave

as simple functions, with the same input-output structure as any other allowed func-

tions described in Section 2.2.

With this information, it is straightforward to create a wrapper function in Python that

performs the following operations:

1. receive and interpret a random input vector sample and a set of deterministic parame-

ters;

2. create a set of input conﬁguration ﬁles/command lines according to the third party

software format;

3. execute the third-party software with the conﬁguration ﬁles just generated;

UQ[PY]LAB-V0.9-103 - 8 -

The Model module

4. retrieve and interpret the results from the output of the executed program;

5. reformat the results and return them in the format required by UQ[PY]LAB.

2.2.4 Creating a UQ[PY]LAB MODEL plugin

The API for UQ[PY]LAB models is quite simple: a wrapper is a Python function of the form:

def myWrapper(X, Parameters):

where X is a N ×M numpy array containing N samples of the M input stochastic parameters,

Parameters is a free-form dictionary containing the static parameters used by the external

software (e.g.command line options, conﬁguration ﬁle names or other conﬁguration options).

The function returns a N ×N

out

numpy array of model responses as calculated by the external

software. The actual implementation of the wrapper is a complete black-box to UQ[PY]LAB.

A simple generic wrapper

Given the great variety of available modelling software, it is impossible to provide a de-

tailed example of a plugin that would be usable on a wide sample of systems. All the wrap-

pers, however, share a common structure that can be summarized in the following pseu-

docode:

import numpy as np

def myWrapper(X, Parameters):

# 1. retrieve the static configuration parameters

config1 = Parameters['Config1']

config2 = Parameters['Config2']

...

# 2. calculate the model response on each sample

Y = []

for x in X:

create_external_input_files(x, config1, config2, ...)

execute_external_code(...)

Y.append(retrieve_results(...))

return np.array(Y, ndmin=2)

The create_external_input_files(x, config1, config2, ...) function trans-

lates the inputs provided by the X matrix and Parameters dictionary into the format required

by the external code, one sample at a time.

The execute_external_code(...) line contains the necessary commands needed by

Python to execute the external code. It may be for example an external program executed

through the Python os.system command.

Finally, the Y.append(retrieve_results(...)) function retrieves the results from the

execution of the external program and appends them to a Python list Y. This function

can be a simple operation that reformats the output of the external software (e.g. if it was

a Python script), or a complex function that reads several ﬁles and merges their results

together. Eventually, the response variable Y is reformatted as a 2D numpy array (N × N

out

)

to ensure consistency.

UQ[PY]LAB-V0.9-103 - 9 -

UQ[PY]LAB user manual

Note that this example is intended to be used only as a generic guideline.

2.3 Cloud-side computational models

UQ[PY]LAB also accepts model deﬁnitions through text strings, that are executed on UQCloud.

Function strings can be used to deﬁne all types of models: vectorized, non-vectorized and

parametric. The convention to write a function string in UQ[PY]LAB is to indicate the ran-

dom variables with the letter X (capital X) and the function parameters with the letter P

(capital P). UQCloud uses the Matlab engine to interpret the function strings. Furthermore,

the list of supported elementary math functions can be found here.

The non-parametric, non-vectorized version of the Ishigami function can be deﬁned as:

modelopts = {

'Type' : 'Model',

'mString' : 'sin(X(1))+7

(sin(X(2))ˆ2)+0.01

(X(3)ˆ4)

sin(X(1))'

}

myModel = uq.createModel(modelopts)

Vectorization

By default function-string-based models in UQ[PY]LAB are assumed to be non-vectorized.

However, it is possible to deﬁne vectorized handles for improved performance by setting the

isVectorized key to true:

modelopts = {

'Type' : 'Model',

'mString' : 'sin(X(:,1))+7

(sin(X(:,2)).ˆ2)+0.01

(X(:,3).ˆ4).

sin(X(:,1))',

'isVectorized' : 1

}

myModel = uq.createModel(modelopts)

Parametric strings

Parametric strings can also be deﬁned by adding the parameters in a variable named P,

and they can be assigned with the Parameters key:

modelopts = {

'Type' : 'Model',

'mString' : 'sin(X(:,1)+P(1)

(sin(X(:,2))ˆ2)+P(2)

(X(:,3)ˆ4)

sin(X(:,1))',

'Parameters': [7, 0.1]

}

myModel = uq.createModel(modelopts)

2.4 Models with multiple outputs

It is sometimes the case that computational models can return more than one output at a

time (N

out

> 1). This is fully supported and there is no need for any extra conﬁguration

options. The vector output responses are expected to be contained in an N × N

out

numpy

array.

UQ[PY]LAB-V0.9-103 - 10 -

Chapter 3

Reference List

How to read the reference list

Python dictionaries play an important role throughout the UQLAB syntax. They offer a natu-

ral way to semantically group conﬁguration options and output quantities. Due to the com-

plexity of the algorithms implemented, it is not uncommon to employ nested dictionaries to

ﬁne-tune the inputs and outputs. Throughout this reference guide, a table-based description

of the conﬁguration dictionaries is adopted.

The simplest case is given when a value of a dictionary key is a simple value or a list:

Table X: Input

Name String A description of the ﬁeld is put here

which corresponds to the following syntax:

Input = {

'Name' : 'My Input'

}

The columns, from left to right, correspond to the name, the data type and a brief description

of each key-value pair. At the beginning of each row a symbol is given to inform as to whether

the corresponding key is mandatory, optional, mutually exclusive, etc. The comprehensive

list of symbols is given in the following table:

Mandatory

□ Optional

⊕ Mandatory, mutually exclusive (only one of

the keys can be set)

⊞ Optional, mutually exclusive (one of them

can be set, if at least one of the group is set,

otherwise none is necessary)

UQ[PY]LAB user manual

When the value of one of the keys of a dictionary is a dictionary itself, a link to a table that

describes the structure of that nested dictionary is provided, as in the case of the Options

key in the following example:

Table X: Input

Name String Description

□ Options Table Y Description of the Options

dictionary

Table Y: Input.Options

Field1 String Description of Field1

□ Field2 Double Description of Field2

In some cases, an option value gives the possibility to deﬁne further options related to that

value. The general syntax would be:

Input = {

'Option1' : 'VALUE1',

'VALUE1' : {

'Val1Opt1' : ... ,

'Val1Opt2' : ...

}

This is illustrated as follows:

Table X: Input

Option1 String Short description

'VALUE1' Description of 'VALUE1'

'VALUE2' Description of 'VALUE2'

⊞ VALUE1 Table Y Options for 'VALUE1'

⊞ VALUE2 Table Z Options for 'VALUE2'

Table Y: Input.VALUE1

□ Val1Opt1 String Description

□ Val1Opt2 Float Description

Table Z: Input.VALUE2

□ Val2Opt1 String Description

UQ[PY]LAB-V0.9-103 - 12 -

The Model module

□ Val2Opt2 Float Description

UQ[PY]LAB-V0.9-103 - 13 -

UQ[PY]LAB user manual

3.1 Create a Model

Syntax

myModel = uq.createModel(Modelopts)

Input

The Python dictionary Modelopts contains the following keys:

Table 1: Modelopts

⊕ ModelFun String To be used for client-side

computational models. A

module-method deﬁnition of the

model function (see Section 2.2.1).

For example, the value A.B.C refers

to a model function deﬁned by the

method C which is retrieved by

from A.B import C

⊕ mString String To be used for cloud-side

computational models. String

containing the model expression (see

Section 2.3). The list of supported

elementary math functions can be

found here.

□ Parameters List or dictionary Non-random model parameters (see

Section 2.2.1)

□ isVectorized Logical

default:

true if ModelFun,

false if mString

Set to true if the model function

supports vectorized input and to

false otherwise

UQ[PY]LAB-V0.9-103 - 14 -

The Model module

Output

After executing the command:

myModel = uq.createModel(Modelopts)

the dictionary myModel is created. It is structured as follows:

Table 2: myModel

Name String Model name

Internal Dictionary Internal keys used during execution

Options Dictionary Original options used to create the model

Parameters List or

dictionary

Parameters dictionary

isVectorized Logical The parameters that are used for the model

evaluations.

mFile String File name of the model function (see

Section 2.2.1)

mString String String deﬁning the model expression (see

Section 2.3)

UQ[PY]LAB-V0.9-103 - 15 -

UQ[PY]LAB user manual

3.2 Evaluate a Model

Syntax

Y = uq.evalModel([myModel, ]X)

[Y1,Y2,...] = uq.evalModel(..., nargout=nargout)

Description

Y = uq.evalModel(X=X) returns the model response of the current MODEL object on the

points X (N × M double). Y has dimension N × N

out

Note: by default, the last created model or surrogate model is the currently active

model.

Y = uq.evalModel(myModel,X) returns the model response of the myModel MODEL ob-

ject on the points X.

Note: For client-side computational models, the syntax

Y = uq.evalModel(myModel,X) is preferable compared to

Y = uq.evalModel(X=X). In the latter case there is an unnecessary call

made to UQCloud to retrieve the currently selected model which is then com-

puted locally whereas in the former case the local model is computed directly

without making any calls to UQCloud.

[Y1,Y2,...] = uq.evalModel(..., nargout=nargout) can be used to return an

nargout number of outputs, if the underlying model supports it.

UQ[PY]LAB-V0.9-103 - 16 -

Bibliography

de Rocquigny, E., N. Devictor, and S. Tarantola (2008). Uncertainty in industrial practice – A

guide to quantitative uncertainty management. John Wiley & Sons. 1

Sudret, B. (2007). Uncertainty propagation and sensitivity analysis in mechanical models -

Contributions to structural reliability and stochastic spectral methods. Habilitation thesis,

Universit

e Blaise Pascal, Clermont-Ferrand, France. 1