hippylib.forward_uq package¶
Submodules¶
hippylib.forward_uq.qoi module¶
-
class
hippylib.forward_uq.qoi.
Qoi
[source]¶ Bases:
object
Abstract class to model the Quantity of Interest. In the following
x
will denote the variable[u, m, p]
, denoting respectively the stateu
, the parameterm
, and the adjoint variablep
.The methods in the class QOI will usually access the state
u
and possibly the parameterm
.-
apply_ij
(i, j, dir, out)[source]¶ Apply the second variation \(\delta_{ij}\) (
i,j = STATE,PARAMETER
) of the cost in directiondir
.
-
eval
(x)[source]¶ Given
x
evaluate the cost functional. Only the stateu
and (possibly) the parameterm
are accessed.
-
hippylib.forward_uq.parameter2QoiMap module¶
-
class
hippylib.forward_uq.parameter2QoiMap.
Parameter2QoiHessian
(p2qoimap)[source]¶ 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)[source]¶ Reshape the Vector
x
so that it is compatible with the reduced Hessian operator.Parameters:
x
- the vector to reshapedim
- if 0 thenx
will be reshaped to be compatible with the range of the reduced Hessian, if 1 thenx
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 ofdolfin.Matrix
.
-
class
hippylib.forward_uq.parameter2QoiMap.
Parameter2QoiMap
(problem, qoi)[source]¶ Bases:
object
Create a parameter-to-qoi map given:
problem
- the description of the forward/adjoint problem and all the sensitivitiesqoi
- the quantity of interest as a function of the state and parameter
-
applyC
(dm, out)[source]¶ Apply the \(C\) block of the Hessian to a (incremental) parameter variable.
out
= \(C dm\)Parameters:
dm
the (incremental) parameter variableout
the action of the \(C\) block on :code:dm
Note
this routine assumes that
out
has the correct shape.
-
applyCt
(dp, out)[source]¶ Apply the transpose of the \(C\) block of the Hessian to a (incremental) adjoint variable.
out
= \(C^T dp\)Parameters:
dp
the (incremental) adjoint variableout
the action of the \(C^T\) block ondp
Note
this routine assumes that
out
has the correct shape.
-
applyWmm
(dm, out)[source]¶ Apply the \(W_{mm}\) block of the Hessian to a (incremental) parameter variable.
out
= \(W_{mm} dm\)Parameters:
dm
the (incremental) parameter variableout
the action of \(W_{mm}\) ondm
Note
this routine assumes that
out
has the correct shape.
-
applyWmu
(du, out)[source]¶ Apply the \(W_{mu}\) block of the Hessian to a (incremental) state variable.
out
= \(W_{mu} du\)Parameters:
du
the (incremental) state variableout
the action of the \(W_{mu}\) block ondu
Note
this routine assumes that
out
has the correct shape.
-
applyWum
(dm, out)[source]¶ Apply the \(W_{um}\) block of the Hessian to a (incremental) parameter variable.
out
= \(W_{um} dm\)Parameters:
dm
the (incremental) parameter variableout
the action of the \(W_{um}\) block ondu
Note
this routine assumes that
out
has the correct shape.
-
applyWuu
(du, out)[source]¶ Apply the \(Wuu\) block of the Hessian to a (incremental) state variable.
out
= \(W_{uu} du\)Parameters:
du
the (incremental) state variableout
the action of the \(W_{uu}\) block ondu
Note
this routine assumes that
out
has the correct shape.
-
eval
(x)[source]¶ 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)[source]¶ 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')[source]¶ By default, return the list
[u, m, p]
where:u
is any object that describes the state variablem
is adolfin.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 onlyu
If
component == PARAMETER
return onlym
If
component == ADJOINT
return onlyp
-
hessian
(m=None, x=None)[source]¶ Evaluate the Hessian of parameter-to-qoi map.
If a relization of the parameter
m
is given, this function will automatically compute the stateu
and adjointp
.As an alternative one can provide directly
x = [u, m, p]
Returns an object of type
ReducedHessianQOI
which provides the Hessian-apply functionality
-
reduced_eval
(m)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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- the parameter variable
m
for assembling the adjoint operator - the state variable
u
for assembling the adjoint right hand side
Note
p
is not accessed- the parameter variable
-
solveAdjIncremental
(sol, rhs)[source]¶ 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)[source]¶ 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- the parameter variable
m
for the solution of the forward problem - the initial guess
u
if the forward problem is non-linear
Note
p
is not accessed- the parameter variable
-
hippylib.forward_uq.parameter2QoiMap.
parameter2QoiMapVerify
(rQOI, m0, h=None, eps=None, plotting=True, verbose=True)[source]¶ 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.taylorApproximationQoi module¶
-
class
hippylib.forward_uq.taylorApproximationQoi.
TaylorApproximationQoi
(p2qoimap, distribution)[source]¶ 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 typeReducedQOI
that describes the parameter-to-qoi mapdistribution
- an object of typehIPPYlib._Prior
that describes the prior Gaussian distribution.
-
computeLowRankFactorization
(Omega)[source]¶ 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 methodk
- the number of eigenpairs to be retained in the LowRank factorization of the prior-preconditioned Hessian.
-
eval
(m, order=2)[source]¶ Evaluates the Taylor approx of the qoi for a given realization of the parameter.
Input:
m
- a specific realization of the uncertain parameterorder
- is the order of the Taylor approximation, currently 1 (linear) or 2 (quadratic)
hippylib.forward_uq.varianceReductionMC module¶
-
hippylib.forward_uq.varianceReductionMC.
varianceReductionMC
(prior, rqoi, taylor_qoi, nsamples, filename='realizations.txt')[source]¶ 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 distributionrqoi
- an object of typeReducedQOI
that describes the parameter-to-qoi maptaylor_qoi
- an object of typeTaylorApproximationQOI
that computes the first and second order Taylor approximation of the qoinsamples
- an integer representing the number of samples for the MC estimatesfilename
- 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.