hippylib.forward_uq package

Submodules

hippylib.forward_uq.qoi module

class hippylib.forward_uq.qoi.Qoi

Bases: object

Abstract class to model the Quantity of Interest. In the following x will denote the variable [u, m, p], denoting respectively the state u, the parameter m, and the adjoint variable p.

The methods in the class QOI will usually access the state u and possibly the parameter m.

apply_ij(i, j, dir, out)

Apply the second variation \(\delta_{ij}\) (i,j = STATE,PARAMETER) of the cost in direction dir.

eval(x)

Given x evaluate the cost functional. Only the state u and (possibly) the parameter m are accessed.

grad(i, x, g)

Evaluate the gradient with respect to the state. Only the state u and (possibly) the parameter m are accessed.

setLinearizationPoint(x)

hippylib.forward_uq.qoi.qoiVerify(qoi, x, generate_state, h=None, plotting=True)

hippylib.forward_uq.qoi.qoiVerifyPlotErrors(eps, err_grad, err_H)

hippylib.forward_uq.parameter2QoiMap module

class hippylib.forward_uq.parameter2QoiMap.Parameter2QoiHessian(p2qoimap)

Bases: object

This class implements matrix free application of the reduced hessian operator.

The constructor takes the following parameters:

• p2qoimap - the object that describes the parameter-to-qoi map

Construct the Hessian Operator of the parameter-to-qoi map

init_vector(x, dim)

Reshape the Vector x so that it is compatible with the reduced Hessian operator.

Parameters:

• x - the vector to reshape
• dim - if 0 then x will be reshaped to be compatible with the range of the reduced Hessian, if 1 then x will be reshaped to be compatible with the domain of the reduced Hessian

Note

Since the reduced Hessian is a self adjoint operator, the range and the domain is the same. Either way, we chose to add the parameter dim for consistency with the interface of dolfin.Matrix.

inner(x, y)

Perform the inner product between x and y in the norm induced by the Hessian \(H\), i.e. \((x, y)_H = x^T H y\)

mult(x, y)

Apply the Hessian of the parameter-to-qoi map to the vector x Return the result in y.

class hippylib.forward_uq.parameter2QoiMap.Parameter2QoiMap(problem, qoi)

Bases: object

Create a parameter-to-qoi map given:

• problem - the description of the forward/adjoint problem and all the sensitivities
• qoi - the quantity of interest as a function of the state and parameter

applyC(dm, out)

Apply the \(C\) block of the Hessian to a (incremental) parameter variable. out = \(C dm\)

Parameters:

• dm the (incremental) parameter variable
• out the action of the \(C\) block on :code:dm

Note

this routine assumes that out has the correct shape.

applyCt(dp, out)

Apply the transpose of the \(C\) block of the Hessian to a (incremental) adjoint variable. out = \(C^T dp\)

Parameters:

• dp the (incremental) adjoint variable
• out the action of the \(C^T\) block on dp

Note

this routine assumes that out has the correct shape.

applyWmm(dm, out)

Apply the \(W_{mm}\) block of the Hessian to a (incremental) parameter variable. out = \(W_{mm} dm\)

Parameters:

• dm the (incremental) parameter variable
• out the action of \(W_{mm}\) on dm

Note

this routine assumes that out has the correct shape.

applyWmu(du, out)

Apply the \(W_{mu}\) block of the Hessian to a (incremental) state variable. out = \(W_{mu} du\)

Parameters:

• du the (incremental) state variable
• out the action of the \(W_{mu}\) block on du

Note

this routine assumes that out has the correct shape.

applyWum(dm, out)

Apply the \(W_{um}\) block of the Hessian to a (incremental) parameter variable. out = \(W_{um} dm\)

Parameters:

• dm the (incremental) parameter variable
• out the action of the \(W_{um}\) block on du

Note

this routine assumes that out has the correct shape.

applyWuu(du, out)

Apply the \(Wuu\) block of the Hessian to a (incremental) state variable. out = \(W_{uu} du\)

Parameters:

• du the (incremental) state variable
• out the action of the \(W_{uu}\) block on du

Note

this routine assumes that out has the correct shape.

eval(x)

Given the list x = [u, m, p] which describes the state, parameter, and adjoint variable compute the QOI.

Note

p is not needed to compute the QOI

evalGradientParameter(x, mg)

Evaluate the gradient for the variational parameter equation at the point x=[u, m, p].

Parameters:

• x = [u, m, p] the point at which to evaluate the gradient.
• mg the variational gradient \((g, mtest)\) being mtest a test function in the parameter space (Output parameter)

generate_vector(component='ALL')

By default, return the list [u, m, p] where:

• u is any object that describes the state variable
• m is a dolfin.Vector object that describes the parameter variable. (Need to support linear algebra operations)
• p is any object that describes the adjoint variable

If component == STATE return only u

If component == PARAMETER return only m

If component == ADJOINT return only p

hessian(m=None, x=None)

Evaluate the Hessian of parameter-to-qoi map.

If a relization of the parameter m is given, this function will automatically compute the state u and adjoint p.

As an alternative one can provide directly x = [u, m, p]

Returns an object of type ReducedHessianQOI which provides the Hessian-apply functionality

init_parameter(m)

Reshape m so that it is compatible with the parameter variable

reduced_eval(m)

Evaluate the parameter-to-qoi map at a given realization m

Note

This evaluation requires the solution of a forward solve

reduced_gradient(m, g)

Evaluate the gradient of parameter-to-qoi map at a given realization m

Note

This evaluation requires the solution of a forward and adjoint solve

setLinearizationPoint(x)

Specify the point x = [u, m, p] at which the Hessian operator needs to be evaluated.

Parameters:

• x = [u, m, p]: the point at which the Hessian needs to be evaluated.

solveAdj(out, x)

Solve the linear adjoint problem.

Parameters:

• out - is the solution of the adjoint problem (i.e. the adjoint p) (Output parameter)

• x = [u, m, p] provides

  1. the parameter variable m for assembling the adjoint operator
  2. the state variable u for assembling the adjoint right hand side

  Note

  p is not accessed

solveAdjIncremental(sol, rhs)

Solve the incremental adjoint problem for a given rhs

Parameters:

• sol the solution of the incremental adjoint problem (Output)
• rhs the right hand side of the linear system

solveFwd(out, x)

Solve the (possibly non-linear) forward problem.

Parameters:

• out - is the solution of the forward problem (i.e. the state) (Output parameters)

• x = [u, m, p] provides

  1. the parameter variable m for the solution of the forward problem
  2. the initial guess u if the forward problem is non-linear

  Note

  p is not accessed

solveFwdIncremental(sol, rhs)

Solve the linearized (incremental) forward problem for a given rhs

Parameters:

• sol the solution of the linearized forward problem (Output)
• rhs the right hand side of the linear system

hippylib.forward_uq.parameter2QoiMap.parameter2QoiMapVerify(rQOI, m0, h=None, eps=None, plotting=True, verbose=True)

Verify the gradient and the Hessian of a parameter-to-qoi map. It will produce two loglog plots of the finite difference checks for the gradient and for the Hessian. It will also check for symmetry of the Hessian.

hippylib.forward_uq.parameter2QoiMap.parameter2QoiMapVerifyPlotErrors(eps, err_grad, err_H)

hippylib.forward_uq.taylorApproximationQoi module

class hippylib.forward_uq.taylorApproximationQoi.TaylorApproximationQoi(p2qoimap, distribution)

Bases: object

This class computes the first and second order Taylor approximation of the parameter-to-qoi map. It provides methods to evaluate the Taylor approximation for a specific realization of the parameter and to analytically compute Expectation and Variance of the Taylor approximation with respect to a Gaussian propability distribution.

Constructor:

• p2qoimap - an object of type ReducedQOI that describes the parameter-to-qoi map
• distribution - an object of type hIPPYlib._Prior that describes the prior Gaussian distribution.

computeLowRankFactorization(Omega)

Compute the LowRank Factorization of the prior-preconditioned Hessian of the parameter-to-qoi map.

The trace of the the prior-preconditioned Hessian is also computed as a post-process of the LowRank factorization.

This method needs to be called before trying to compute the moments of the the quadratic Taylor approx of the parameter-to-qoi map.

Inputs:

• Omega - Gaussian random matrix for randomized method
• k - the number of eigenpairs to be retained in the LowRank factorization of the prior-preconditioned Hessian.

eval(m, order=2)

Evaluates the Taylor approx of the qoi for a given realization of the parameter.

Input:

• m - a specific realization of the uncertain parameter
• order - is the order of the Taylor approximation, currently 1 (linear) or 2 (quadratic)

expectedValue(order=2)

Returns the expected value (computed analytically) of the qoi with respect to a Gaussian distribution for the parameter.

Input:

• order - is the order of the Taylor approximation, currently 1 (linear) or 2 (quadratic)

variance(order=2)

Returns the variance (computed analytically) of the qoi with respect to a Gaussian distribution for the parameter.

Input:

• order - is the order of the Taylor approximation, currently 1 (linear) or 2 (quadratic)

hippylib.forward_uq.taylorApproximationQoi.plotEigenvalues(d)

Plots the eigenvalues d in a semilogy scale. Positive eigenvalues are marked in blue, negative eigenvalues are marked in red.

hippylib.forward_uq.varianceReductionMC module

hippylib.forward_uq.varianceReductionMC.varianceReductionMC(prior, rqoi, taylor_qoi, nsamples, filename='realizations.txt')

This function computes Monte Carlo Estimates for forward propagation of uncertainty. The uncertain parameter satisfies a Gaussian distribution with known mean and covariance (describes as the inverse of a differential operator). Convergence of the Monte Carlo estimates is accelerated using a variance reduction techinque based on a Taylor approximation of the parameter-to-qoi map.

Inputs:

• prior - an object of type :code:hIPPYlib._Prior` that allows to generate samples from the prior distribution
• rqoi - an object of type ReducedQOI that describes the parameter-to-qoi map
• taylor_qoi - an object of type TaylorApproximationQOI that computes the first and second order Taylor approximation of the qoi
• nsamples - an integer representing the number of samples for the MC estimates
• filename - a string containing the name of the file where the computed qoi and its Taylor approximations (for each realization of the parameter) are saved

Outputs:

• Sample mean of the quantity of interest q, its Taylor approx q1 and q2, and corrections y1=q-q1 and y2=q-q2.
• MSE (Mean square error) of the standard MC, and the variance reduced MC using q1 and q2.

Note

The variate control MC estimator can be computed off-line by postprocessing the file containing the values of the computed qoi and Taylor approximations.

Module contents