<< setrandvar NISP Tutorials >>

NISP >> NISP > polychaos

polychaos

A class to manage a Polynomial Chaos expansion.

Static Functions

tokenmatrix=polychaos_tokens ()
nb=polychaos_size ()

Creation/Destruction

pc=polychaos_new ( file)
pc=polychaos_new ( srv,ny)
pc=polychaos_new(pc,nopt,varopt)
polychaos_destroy (pc)

Methods: Target

polychaos_setsizetarget(pc,np)
np=polychaos_getsizetarget(pc)
polychaos_settarget(pc,k,j,output)
polychaos_settarget(pc,k,output)
polychaos_settarget(pc,output)
output=polychaos_gettarget(pc,k,j)
output=polychaos_gettarget(pc,k)
output=polychaos_gettarget(pc)
polychaos_freememtarget(pc)
polychaos_readtarget(pc,file)

Methods: Configuration

polychaos_setdegree(pc,no)
no=polychaos_getdegree(pc)
polychaos_setdimoutput(pc,ny)
ny=polychaos_getdimoutput(pc)
nx=polychaos_getdiminput(pc)
p=polychaos_getdimexp(pc)
polychaos_computeexp(pc,srv,method)
polychaos_computeexp(pc,pc2,invalue,varopt)

Methods: Sensitivity Analysis

m=polychaos_getmean(pc,ovar)
m=polychaos_getmean(pc)
v=polychaos_getvariance(pc,ovar)
v=polychaos_getvariance(pc)
st=polychaos_getindextotal(pc,ivar,ovar)
st=polychaos_getindextotal(pc,ivar)
st=polychaos_getindextotal(pc)
s=polychaos_getindexfirst(pc,ivar,ovar)
s=polychaos_getindexfirst(pc,ivar)
s=polychaos_getindexfirst(pc)
c=polychaos_getcovariance(pc,ovar1,ovar2)
c=polychaos_getcovariance(pc)
c=polychaos_getcorrelation(pc,ovar1,ovar2)
c=polychaos_getcorrelation(pc)

Methods: Groups of variables

polychaos_setgroupempty(pc)
polychaos_setgroupaddvar(pc,ivar)
polychaos_printgroup(pc)
g=polychaos_getgroup(pc)
s=polychaos_getgroupinter(pc,ovar)
s=polychaos_getgroupinter(pc)
st=polychaos_getgroupind(pc,ovar)
st=polychaos_getgroupind(pc)

Methods: Data files

polychaos_generatecode(pc,filename,funname)
polychaos_save(pc,file)

Methods: Meta-Model

output=polychaos_compute(pc,input)

Methods: Sampling

polychaos_buildsample(pc,type,np,order)
sampling=polychaos_getsample(pc,k,ovar)
sampling=polychaos_getsample(pc,k)
sampling=polychaos_getsample(pc)

Methods: Quantiles

x=polychaos_getquantile(pc,alpha,ovar)
x=polychaos_getquantile(pc,alpha)
x=polychaos_getquantwilks(pc,walpha,wbeta,ovar)
x=polychaos_getquantwilks(pc,walpha,wbeta)
p=polychaos_getinvquantile(pc,threshold,ovar)
p=polychaos_getinvquantile(pc,threshold)

Methods: Miscellaneous

polychaos_sasummary(pc)
polychaos_realisation(pc)
polychaos_getlog(pc)
polychaos_getmultind(pc)
polychaos_getanovaordco(pc,threshold,r)
polychaos_getanovaordco(pc,threshold)
polychaos_getanovaord(pc)
polychaos_getanova(pc)
polychaos_getanova(pc,r)

Description

The polychaos_new function allows to create a new polynomial. The polychaos_destroy function allows to destroy an existing polynomial.

The polychaos_new function returns a token which is a unique identifier for the new polynomial. Indeed, when a new polynomial is created, a counter is updated which corresponds to the returned token. This way, each token is unique and can correspond only to one single polynomial.

The functions polychaos_tokens and polychaos_size allow to manage the polynomials which have already been created. The function polychaos_size returns the number of polynomials, while the polychaos_tokens function returns the list of current polynomials.

Static Functions

tokenmatrix=polychaos_tokens ()

Returns a 1-by-n matrix of doubles, positive integers, representing the current polychaos tokens, where n is the number of tokens.

n=polychaos_size ()

Returns a 1-by-1 matrix containing the current number of polychaos tokens currently in use, where n is the number of tokens.

Creation/Destruction

pc=polychaos_new ( srv,ny)

Creates a new PolynomialChaos based on given SetRandomVariable srv and number of output ny, where ny is a 1-by-1 matrix of doubles, positive integers.

pc=polychaos_new(pc,nopt,varopt)

Create a new polychaos from another polychaos and an array of integers varopt with size nopt (to deal with optimisation with uncertainties).

pc=polychaos_new ( file)

Creates a new polychaos from a data file, where fil is a 1-by-1 matrix of strings.

polychaos_destroy (pc)

Destroys the current polynomial.

Methods: Target

polychaos_setsizetarget(pc,np)

Set the number of experiments to np, where np is a 1-by-1 matrix of doubles.

np=polychaos_getsizetarget(pc)

Returns the number of experiments.

polychaos_settarget(pc,k,j,output)

Set the output value for experiment #k and output #j, where 1 ≤ k ≤ np and 1 ≤ j ≤ ny and output is a 1-by-1 matrix of doubles.

polychaos_settarget(pc,k,output)

Set the output for experiment #k to the matrix output, where 1 ≤ k ≤ np, where np is the number of experiments and output is a 1-by-ny matrix of doubles, where ny is the number of output random variables.

polychaos_settarget(pc,output)

Set the output matrix where output is a np-by-ny matrix of doubles, where np is the number of experiments and ny is the number of ouput random variables.

output=polychaos_gettarget(pc,k,j)

Returns the output value for experiment #k and input random variable #j, where 1 ≤ k ≤ np and 1 ≤ j ≤ nx and output is a 1-by-1 matrix of doubles.

output=polychaos_gettarget(pc,k)

returns the output value for experiment #k and input #j, where 1 ≤ k ≤ np where output is a 1-by-nx matrix of doubles with nx the number of input random variables.

output=polychaos_gettarget(pc)

Returns the output np-by-nx matrix of doubles, where np is the number of experiments and nx is the number of input random variables.

polychaos_freememtarget(pc)

Free the memory associated with the output of the experiments.

polychaos_readtarget(pc,file)

Read the output of the experiments from the file.

Methods: Configuration

polychaos_setdegree(pc,no)

Set the degree of the polynomial to no, a 1-by-1 matrix of doubles.

no=polychaos_getdegree(pc)

Returns the degree of the polynomial.

polychaos_setdimoutput(pc,ny)

Set the number of output random variables to ny, a 1-by-1 matrix of doubles, positive integer.

ny=polychaos_getdimoutput(pc)

Returns ny, a 1-by-1 matrix of doubles, positive integer, the number of output random variables.

nx=polychaos_getdiminput(pc)

Returns nx, a 1-by-1 matrix of doubles, positive integer, the number of input random variables.

p=polychaos_getdimexp(pc)

Returns p, a 1-by-1 matrix of doubles, positive integer, the dimension of the expansion.

polychaos_computeexp(pc,srv,method)

Computes the coefficients of the polynomial chaos expansion where srv is a setrandvar token and method is a 1-by-1 matrix of strings representing the computation algorithm.

The list of possible values for method is :

  • "Integration"

  • "Regression"

polychaos_computeexp(pc,pc2,invalue,varopt)

Compute the coefficient of pc based on another polynomial chaos pc2, by setting some input variables which indices are given in varopt to a constant value given in invalue. The polynomial pc2 has n variables while pc has n-nopt variables where nopt < n. The variables invalue and varopt should both be column vectors, with the same number of rows nopt. The invalue variable contains input values of the stochastic variable x, while the variable varopt contains input variable indices.

Methods: Sensitivity Analysis

m=polychaos_getmean(pc,ovar)

Returns a 1-by-1 matrix of doubles, the mean of the output variable which index is ovar, where 1 ≤ ovar ≤ ny, where ny is the number of output random variables.

m=polychaos_getmean(pc)

Returns a 1-by-ny matrix of doubles, the mean of the all output variables, where ny is the number of output random variables.

v=polychaos_getvariance(pc,ovar)

Returns a 1-by-1 matrix of doubles, the variance of the output variable which index is ovar, where 1 ≤ ovar ≤ ny.

v=polychaos_getvariance(pc)

Returns a 1-by-ny matrix of doubles, the variance of the all output variables, where ny is the number of output random variables.

st=polychaos_getindextotal(pc,ivar,ovar)

Returns a 1-by-1 matrix of doubles, the total index for the input variable #ivar and the output variable #ovar, where 1≤ ivar ≤ nx where nx is the number of input random variables and 1 ≤ ovar ≤ ny where ny is the number of output random variables.

st=polychaos_getindextotal(pc,ivar)

Returns a 1-by-ny matrix of doubles, the total index of the input variable #ivar and the output variable #ovar=1, where 1 ≤ ivar ≤ nx where nx is the number of input random variables, and ny is the number of output random variables.

st=polychaos_getindextotal(pc)

Returns a nx-by-ny matrix of doubles, all total indices, where nx is the number of input random variables and ny is the number of output random variables.

s=polychaos_getindexfirst(pc,ivar,ovar)

Returns a 1-by-1 matrix of doubles, the first index order of the input variable #ivar and the output variable #ovar, where 1 ≤ ivar ≤ nx and 1 ≤ ovar ≤ ny, with nx is the number of input random variables and ny is the number of output random variables.

s=polychaos_getindexfirst(pc,ivar)

Returns a 1-by-ny matrix of doubles, the first index order of the input variable #ivar and the output variable #ovar=1, where 1 ≤ ivar ≤ nx, with nx the number of input random variables and ny is the number of output random variables.

s=polychaos_getindexfirst(pc)

Returns a nx-by-ny matrix of doubles, all first index order indices, with nx is the number of input random variables and ny is the number of output random variables.

c=polychaos_getcovariance(pc,ovar1,ovar2)

Returns a 1-by-1 matrix of doubles, the covariance of the output random variables #ovar1 and #ovar2, where 1 ≤ ovar1, ovar2 ≤ ny, where ny is the number of output random variables.

c=polychaos_getcovariance(pc)

Returns a ny-by-ny matrix of doubles, the covariance of the all output variables, where ny is the number of output random variables.

c=polychaos_getcorrelation(pc,ovar1,ovar2)

Returns a 1-by-1 matrix of doubles, the correlation of the output random variables #ovar1 and #ovar2, where 1 ≤ ovar1, ovar2 ≤ ny, where ny is the number of output random variables.

c=polychaos_getcorrelation(pc)

Returns a ny-by-ny matrix of doubles, the correlation of the all output variables, where ny is the number of output random variables.

Methods: Groups of variables

polychaos_setgroupaddvar(pc,ivar)

Adds an input variable ivar to the group, with 1 ≤ ivar ≤ nx, where nx is the number of input random variables.

s=polychaos_getgroupinter(pc,ovar)

Returns a 1-by-1 matrix of doubles, the first order interaction indice of an output variable ovar, where 1 ≤ ovar ≤ ny, where ny is the number of output random variables. This takes into account for the effect of only the interaction of the variables within the group.

s=polychaos_getgroupinter(pc)

Returns a 1-by-ny matrix of doubles, all first order interaction indices, where ny is the number of output random variables. This takes into account for the effect of only the interaction of the variables within the group.

st=polychaos_getgroupind(pc,ovar)

Returns a 1-by-1 matrix of doubles, the total sensitivity indice of an output variable ovar, where 1 ≤ ovar ≤ ny, where ny is the number of output random variables. This takes into account for the effect of all the variables within the group.

st=polychaos_getgroupind(pc)

Returns a 1-by-ny matrix of doubles, all total sensitivity indices, where ny is the number of output random variables. This takes into account for the effect of all the variables within the group.

polychaos_setgroupempty(pc)

Set the current group of input random variables as empty.

When a polychaos object is created, the current group of variables is empty.

This function can be useful if, after having analysed a first group of variable, we want to analyse a second group. In this case, we first call the polychaos_setgroupempty function to set the group as empty. Then we call the polychaos_setgroupaddvar function to add the variables in the group.

polychaos_printgroup(pc)

Print the current group of variables.

g=polychaos_getgroup(pc)

Returns the current group of variables. The matrix g is a n-by-1 matrix of doubles, integer value, where n is the current number of variables in the group.

Methods: Data Files

polychaos_generatecode(pc,filename,funname)

Generates the source code to compute the polynomial chaos into the file filename. The generated function name is funname.

polychaos_save(pc,file)

Saves the polynomial chaos into file.

Methods: Meta-Model

output=polychaos_compute(pc,input)

Compute the output as a 1-by-ny matrix of doubles, depending on the input as a 1-by-nx matrix of doubles. Evaluates the value of the chaos polynomial (uses it as a meta-model).

Methods: Sampling

The functions in this section allows to use the polynomial chaos meta-model to estimate some characteristic of the actual model. The polychaos_buildsample function builds an internal sample and evaluates the polynomial chaos on this sampling. Then, the polychaos_getquantile, for example, can be used, which approximates the quantile of the actual model, by estimating the quantile of the meta-model.

polychaos_buildsample(pc,type,np)

Build an internal sampling of given type with size np, where type is a 1-by-1 matrix of strings, np is a 1-by-1 matrix of doubles, positive integer.

The list of possible values for the input argument "type" is the following.

  • "MonteCarlo"

  • "Lhs"

  • "QmcSobol"

sampling=polychaos_getsample(pc,k,ovar)

Returns a 1-by-1 matrix of doubles, the sample of experiment #k, where 1 ≤ k ≤ np, for output variable #ovar, where 1 ≤ ovar ≤ ny, where k is a 1-by-1 matrix of doubles, positive integer and over is a 1-by-1 matrix of doubles, positive integer.

sampling=polychaos_getsample(pc,k)

Returns a 1-by-ny matrix of doubles, the sample of experiment #k, where 1 ≤ k ≤ np, where ny is the number of output random variables, and k is a 1-by-1 matrix of doubles, positive integer.

sampling=polychaos_getsample(pc)

Returns a np-by-ny matrix of doubles, where np is the number of experiments and ny is the number of output random variables.

Methods: Quantiles

The polychaos_buildsample method must be called at least once before calling the functions in this section. Then, the quantiles, for example, are computed based on the evaluation of the polynomial chaos on the sampling.

y=polychaos_getquantile(pc,alpha,ovar)

Returns a 1-by-1 matrix of doubles, the quantile of order alpha for output random variable #ovar, where 1 ≤ ovar ≤ ny, where ny is the number of output random variables. I.e. returns y such that P(Y< y)=alpha, where Y is the output of the model.

y=polychaos_getquantile(pc,alpha)

Returns a 1-by-ny matrix of doubles, the quantiles of order alpha for all output variables, where ny is the number of output random variables.

y=polychaos_getquantwilks(pc,alpha,beta,ovar)

Returns a 1-by-1 matrix of doubles, the Wilks quantile of order alpha with confidence beta for output variable #ovar, where 1 ≤ ovar ≤ ny

y=polychaos_getquantwilks(pc,alpha,beta)

Returns a 1-by-ny matrix of doubles, the Wilks quantiles of order alpha with confidence beta for all output variables, where ny is the number of output random variables.

p=polychaos_getinvquantile(pc,threshold,ovar)

Returns a 1-by-1 matrix of doubles, the probability of having an output variable ovar lower than threshold, where 1 ≤ ovar ≤ ny with ny the number of output random variables. I.e. returns p=P(Y< threshold), where Y is the output of the model.

p=polychaos_getinvquantile(pc,threshold)

Returns a 1-by-ny matrix of doubles, the probability of having an output variable lower than threshold, with ny the number of output random variables.

Methods: Miscellaneous

polychaos_sasummary(pc)

Prints a summary of the sensitivity analysis.

polychaos_realisation(pc)

A realisation of the polynomial chaos viewed as a random variable. The scalar value is obtained via value=polychaos_getoutput(pc,ovar) where 1 ≤ ovar ≤ ny or as a vector with value=polychaos_getoutput(pc)

polychaos_getlog(pc)

Prints out a log of current polynomial.

polychaos_getmultind(pc)

Prints the multiple indices.

polychaos_getanovaordco(pc,threshold,ovar)

Prints out the anova ordered coefficients until the fraction of the variance is less of threshold for the output of rank ovar with 1 ≤ ovar ≤ ny

polychaos_getanovaordco(pc,threshold)

Prints out the anova ordered coefficients until the fraction of the variance is less of threshold for the first output.

polychaos_getanovaord(pc)

Prints out the anova ordered coefficients.

polychaos_getanova(pc)

Prints out the anova for the first output.

polychaos_getanova(pc,ovar)

Prints out the anova for the output of rank ovar with 1 ≤ ovar ≤ ny

Example

In the following example, we perform the sensitivity analysis of a problem which has two input random variables and one random output variable. The function Exemple computes the product of the two entries of x. The first variable has a "Normale" distribution while the second variable has a "Uniforme" distribution.

function y=Exemple(x)
y = x(:,1) .* x(:,2);
endfunction
// 1. Two stochastic (normalized) variables
vx1 = randvar_new("Normale");
vx2 = randvar_new("Uniforme");
// 2. A collection of stoch. variables.
srvx = setrandvar_new();
setrandvar_addrandvar ( srvx,vx1);
setrandvar_addrandvar ( srvx,vx2);
// 3. Two uncertain parameters
vu1 = randvar_new("Normale",1.0,0.5);
vu2 = randvar_new("Uniforme",1.0,2.5);
// 4. A collection of uncertain parameters
srvu = setrandvar_new();
setrandvar_addrandvar ( srvu,vu1);
setrandvar_addrandvar ( srvu,vu2);
// 5. Create the Design Of Experiments
degre = 2;
setrandvar_buildsample(srvx,"Quadrature",degre);
setrandvar_buildsample( srvu,srvx);
// 6. Create the polynomial
ny = 1;
pc=polychaos_new ( srvx,ny);
np = setrandvar_getsize(srvx);
polychaos_setsizetarget(pc,np);
// 7. Perform the DOE
inputdata = setrandvar_getsample(srvu);
outputdata = Exemple(inputdata);
polychaos_settarget(pc,outputdata);
// 8. Compute the coefficients of the polynomial expansion
polychaos_setdegree(pc,degre);
polychaos_computeexp(pc,srvx,"Integration");
// 9. Get the sensitivity indices
// 9.1 Print a summary
polychaos_sasummary(pc);
// 9.2 Get the sensitivity indices
average=polychaos_getmean(pc)
var=polychaos_getvariance(pc)
// First order sensitivity indices
polychaos_getindexfirst(pc)
// Total sensitivity indices
polychaos_getindextotal(pc)
// Clean-up
nisp_destroyall();

The previous script produces the following output.

-->polychaos_sasummary(pc);
      Mean     = 1.75
      Variance = 1
      First order sensitivity indices
      Output #1
      Variable X1 = 0.765625
      Variable X2 = 0.1875
      Total sensitivity indices
      Output #1
      Variable X1 = 0.8125
      Variable X2 = 0.234375
      Functional ANOVA:
      1 0  : 0.765625
      0 1  : 0.1875
      1 1  : 0.046875
-->// 9.2 Get the sensitivity indices
-->average=polychaos_getmean(pc)
      average  =
      1.75
-->var=polychaos_getvariance(pc)
      var  =
      1.
-->// First order sensitivity indices
-->polychaos_getindexfirst(pc)
      ans  =
      0.765625
      0.1875
-->// Total sensitivity indices
-->polychaos_getindextotal(pc)
      ans  =
      0.8125
      0.234375
    

Managing a group of variables

We can manage a group of variables and measure the sensitivity indices of this group. When a new polychaos object is created, the associated group of variables is empty. Then, we can add variables in the group with the polychaos_setgroupaddvar function. Once this is done, we can call the polychaos_getgroupind function to get the total sensitivity indices of the variables in the group. We can also call the polychaos_getgroupinter function to get the first order sensitivity indices associated with the interaction of the variables in the group.

Once this is done, we may analyse a new group of variables. To do this, we must first make the current group empty with a call to the polychaos_setgroupempty function.

At any time, we can know which variables are in the group. The polychaos_printgroup function prints the current variables in the group. Moreover, the polychaos_getgroup function returns the indices of the variables in the group.

In the following example, we load two functions which creates and cleanup a sample polynomial chaos. These functions define the same test-case as in the previous example. Then we create various groups of variables and analyse their sensitivity indices.

// Load several functions required for the test.
path = nisp_getpath();
testpath = fullfile(path,"tests","unit_tests","polychaos");
exec(fullfile(testpath,"createMyPolychaos.sci"));
exec(fullfile(testpath,"cleanupMyPolychaos.sci"));

// Test polychaos_getgroupind ( pc,ovar )
// Test polychaos_getgroupind ( pc )
[ pc,srvx,rvx1,rvx2,srvu,vu1,vu2 ] = createMyPolychaos();
polychaos_computeexp(pc,srvx,"Integration");
// Use an empty group:
polychaos_printgroup(pc);
g = polychaos_getgroup(pc)
computed = polychaos_getgroupind ( pc,1 )
// Add the first variable:
polychaos_setgroupaddvar ( pc,1 );
polychaos_printgroup(pc);
g = polychaos_getgroup(pc)
computed = polychaos_getgroupind ( pc )
// Add the second variable:
polychaos_setgroupaddvar ( pc,2 );
polychaos_printgroup(pc);
g = polychaos_getgroup(pc)
computed = polychaos_getgroupind ( pc )
//
// Analyse a second group of variables
// Make the group empty
polychaos_setgroupempty(pc);
polychaos_printgroup(pc);
g = polychaos_getgroup(pc)
// Add the second variable:
polychaos_setgroupaddvar ( pc,2 );
polychaos_printgroup(pc);
g = polychaos_getgroup(pc)
computed = polychaos_getgroupind ( pc )
//
cleanupMyPolychaos ( pc,srvx,rvx1,rvx2,srvu,vu1,vu2 );

Authors

Copyright (C) 2012-2013 - Michael Baudin

Copyright (C) 2008-2011 - CEA - Jean-Marc Martinez

Copyright (C) 2008-2011 - INRIA - Michael Baudin


Report an issue
<< setrandvar NISP Tutorials >>