The NISP Module

In this page, we present the Non Intrusive Spectral Projection (NISP) module available in Scilab since the 29th of September 2009.

Contents

  1. The NISP Module
    1. Introduction
    2. Features
    3. How to get the module
      1. Forge
      2. How to install the module
    4. Documentation
    5. Teaching
      1. Session 2009-2010
      2. Session 2010-2011
      3. Session 2011-2012
    6. Examples
      1. The product function
      2. The Ishigami function
    7. NISP v2.2
    8. NISP v2.3
    9. Authors

Introduction

This toolbox allows to approximate a given model, which is associated with input random variables.

The module provides the following components :

The current toolbox provides an object-oriented approach of the C++ NISP library.

This toolbox has been created in the context of the OPUS project :

http://opus-project.fr/

within the workpackage 2.1.1 "Construction de méta-modèles".

This project has received funding by Agence Nationale de la recherche :

http://www.agence-nationale-recherche.fr/

Features

Main Features:

Configuration Functions:

Sensitivity Analysis Functions:

Support functions:

Test functions:

How to get the module

Forge

The Scilab Forge hosts the sources of the module:

http://forge.scilab.org/index.php/p/nisp/

How to install the module

The module is available under ATOMS :

http://atoms.scilab.org/toolboxes/NISP

To install it, type the following statement in the Scilab console (Scilab version >= 5.1): 

atomsInstall("NISP")

Documentation

See in the help provided in the help/en_US directory of the toolbox for more information about its use. Use cases are presented in the demos directory.

This module has been presented at the "42èmes Journées de Statistique", du 24 au 28 mai 2010 - Marseille, France. The title was "Polynômes de chaos sous Scilab via la librairie NISP", Michaël Baudin, Jean-Marc Martinez, 2010 and the talk has been given the 28th of May 2010.

The following User's Manual presents the toolbox :

The NISP module for Scilab has been presented at the OPUS Final workshop, "Computer experiments and uncertainty analysis" Friday, October 21, 2011 Henri Poincaré Institute, France. The title was "Polynômes du chaos et analyse de sensibilité : zoom sur les outils disponibles dans Scilab", Michaël Baudin, Jean-Marc Martinez, 2011

Teaching

The NISP module is used to teach sensitivity analysis to Master's students at INSTN. The master is "Master de Modélisation et Simulation" (M2S) :

http://www.maisondelasimulation.fr/m2s/

This session is within the course "Calcul hautes performances", Informatique scientifique approfondie (I1), Traitement des incertitudes (I1c).

Session 2009-2010

Session 2010-2011

Session 2011-2012

Examples

In this section, we present two simple examples of use of this module.

The product function

In the following example, we compute the polynomial chaos expansion of a very simple function, taking two input variables and returning one output variable. The output result is computed by the Exemple function as the product of the two inputs. The first variable is associated with a Normal law, while the second is associated with a Uniform law. 

// Copyright (C) 2009 - CEA - Jean-Marc Martinez
// Copyright (C) 2008-2009 - INRIA - Michael Baudin
//
// This file must be used under the terms of the GNU Lesser General Public License license :
// http://www.gnu.org/copyleft/lesser.html
//

// Test the chaos polynomial decomposition on the product x1*x2 function.
// Two random variables:
// * a normal random variable with mu=1.0 and sigma=0.5,
// * a uniform random variable in [1,2.5].
// Create a Quadrature sampling and compute the coefficients of the polynomial 
// by integration.
// Use a degree 2 polynomial.

function y = Exemple (x)
  // Returns the output y of the product x1 * x2.
  // Parameters
  // x: a np-by-nx matrix of doubles, where np is the number of experiments, and nx=2.
  // y: a np-by-1 matrix of doubles
  y(:,1) = 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
average = polychaos_getmean(pc);
var = polychaos_getvariance(pc);
mprintf("Mean     = %f\n",average);
mprintf("Variance = %f\n",var);
S = polychaos_getindexfirst(pc);
mprintf("S1 = %f\n",S(1));
mprintf("S2 = %f\n",S(2));
ST = polychaos_getindextotal(pc);
mprintf("ST1 = %f\n",ST(1));
mprintf("ST2 = %f\n",ST(2));
// Clean-up
polychaos_destroy(pc);
randvar_destroy(vu1);
randvar_destroy(vu2);
randvar_destroy(vx1);
randvar_destroy(vx2);
setrandvar_destroy(srvu);
setrandvar_destroy(srvx);

The previous script produces the following output. 

Mean     = 1.750000
Variance = 1.000000
S1 = 0.765625
S2 = 0.187500
ST1 = 0.812500
ST2 = 0.234375

The Ishigami function

In the following example, we compute the polynomial chaos expansion of the Ishigami function, which has 3 inputs and 1 output. The three input variables are uniform random variables in the interval [-Pi,Pi]. 

// Copyright (C) 2009 - CEA - Jean-Marc Martinez
// Copyright (C) 2009-2011 - INRIA - Michael Baudin
//
// This file must be used under the terms of the GNU Lesser General Public License license :
// http://www.gnu.org/copyleft/lesser.html

//
// Test the chaos polynomial decomposition on the Ishigami function.
// Three uniform variables in [-pi,pi].
// Create a Petras sampling and compute the coefficients of the polynomial 
// by integration.
//



// 3 random variable uniform in [-pi,pi]
a=7.;
b=0.1;
exact = nisp_ishigamisa ( a , b );

// 1. Create a group of stochastic variables
nx = 3;
srvx = setrandvar_new( nx );

// 2. Create a group of uncertain variables
rvu1 = randvar_new("Uniforme",-%pi,%pi);
rvu2 = randvar_new("Uniforme",-%pi,%pi);
rvu3 = randvar_new("Uniforme",-%pi,%pi);
srvu = setrandvar_new();
setrandvar_addrandvar ( srvu, rvu1);
setrandvar_addrandvar ( srvu, rvu2);
setrandvar_addrandvar ( srvu, rvu3);

// 3. Create a Petras sampling
degre = 9;
setrandvar_buildsample(srvx,"Petras",degre);
setrandvar_buildsample( srvu , srvx );

// 4. Create the chaos polynomial
pc = polychaos_new ( srvx , 1 );
polychaos_setdegree(pc,degre);

// 5. Perform the experiments
np = setrandvar_getsize(srvu);
mprintf("Number of experiments = %d\n",np);
polychaos_setsizetarget(pc,np);
inputdata = setrandvar_getsample(srvu);
outputdata = nisp_ishigami(inputdata,a,b);
polychaos_settarget(pc,outputdata);

// 6. Compute the coefficients by integration
polychaos_computeexp(pc,srvx,"Integration");

// 7. Get the sensitivity indices
average = polychaos_getmean(pc);
var = polychaos_getvariance(pc);

mprintf("Mean        = %f (expected=%f)\n",average,exact.expectation);
mprintf("Variance    = %f (expected=%f)\n",var,exact.var);
S = polychaos_getindexfirst (pc);
mprintf("S1    = %f (expected=%f)\n",S(1),exact.S1);
mprintf("S2    = %f (expected=%f)\n",S(2),exact.S2);
mprintf("S3    = %f (expected=%f)\n",S(3),exact.S3);
ST = polychaos_getindextotal (pc);
mprintf("ST1    = %f (expected=%f)\n",ST(1),exact.ST1);
mprintf("ST2    = %f (expected=%f)\n",ST(2),exact.ST2);
mprintf("ST3    = %f (expected=%f)\n",ST(3),exact.ST3);

// Consider the group {X1,X2}
groupe = [1 3];
polychaos_setgroupempty ( pc );
polychaos_setgroupaddvar ( pc , groupe(1) );
polychaos_setgroupaddvar ( pc , groupe(2) );
mprintf("Group {X1,X3}\n");
ST13=exact.S1+exact.S3+exact.S13;
mprintf("    ST13 =%f (expected=%f)\n",polychaos_getgroupind(pc),ST13);
mprintf("    S13  =%f (expected=%f)\n",polychaos_getgroupinter(pc),exact.S13);

// Compute all sensitivity indices.
// The line [1 0 1] is associated with the group {X1,X3}.
// The sum of all sensitivity indices is equal to 1.
mprintf("Anova decomposition of the normalized variance.\n");
polychaos_getanova(pc);

// Compute the histogram of the output of the chaos polynomial.
polychaos_buildsample(pc,"Lhs",10000,0);
sample_output = polychaos_getsample(pc);
my_handle = scf(10001);
histplot(50,sample_output)
xtitle("Ishigami - Histogram");

// Plot the sensitivity indices.
for i=1:nx
  indexfirst(i)=polychaos_getindexfirst(pc,i);
  indextotal(i)=polychaos_getindextotal(pc,i);
end
my_handle = scf(10002);
bar(indextotal,0.2,'blue');
bar(indexfirst,0.15,'yellow');
legend(["Total" "First order"],pos=1);
xtitle("Ishigami - Sensitivity index");
//
// Clean-up
//
randvar_destroy ( rvu1 );
randvar_destroy ( rvu2 );
randvar_destroy ( rvu3 );
setrandvar_destroy ( srvu );
polychaos_destroy ( pc );
setrandvar_destroy ( srvx );

The previous script produces the following output. 

Number of experiments = 751
Mean        = 3.500000 (expected=3.500000)
Variance    = 13.842473 (expected=13.844588)
S1    = 0.313953 (expected=0.313905)
S2    = 0.442325 (expected=0.442411)
S3    = 0.000000 (expected=0.000000)
ST1    = 0.557675 (expected=0.557589)
ST2    = 0.442326 (expected=0.442411)
ST3    = 0.243721 (expected=0.243684)
Group {X1,X3}
    ST13 =0.557674 (expected=0.557589)
    S13  =0.243721 (expected=0.243684)
Anova decomposition of the normalized variance.
1 0 0  : 0.313953
0 1 0  : 0.442325
1 1 0  : 1.55229e-009
0 0 1  : 8.08718e-031
1 0 1  : 0.243721
0 1 1  : 8.43733e-031
1 1 1  : 1.6007e-007

The previous script produces the following plots.

ishigami-histogram.svg

ishigami-sensitivityindices.svg

NISP v2.2

The main changes for this release are the following.

Here is the detailed changelog for the v2.2:

NISP v2.3

The main changes for this release are the following.

Here is the detailed changelog for the v2.3:

Authors

public: NISP Module (last edited 2012-02-17 17:15:16 by michael.baudin@scilab.org)