Introduction

This guide aims at facilitating the use of OpenTURNS through its textual User interface (TUI), by proposing numerous examples of TUI studies.

The presentation of the Use Cases Guide follows the methodology of uncertainty treatment presented in the scientific documentation of OpenTURNS : examples are divided into four steps corresponding to the four steps of an uncertainty treatment study.

The example list presented here is not exhaustive but recovers most of the standard User needs. The TUI enables the User to perform much more functionalities of the openturns python library than those presented here : it is necessary for the User to refer to the complete python documentation of the openturns python library to have the whole list of what is possible to perform.

It is important to note that the python test files given in open source with the code source of OpenTURNS are very useful : they provide to the User an example of the utilisation of each object of OpenTURNS. The User is invited to refer to them : they will surely help him to write his study through the TUI with the right syntax.

Loading the openturns python library

In order to write a python file using fonctionalities proposed by the openturns python module, it is necessary to load the module in the python shell. If there is no danger to overload functionalities coming from other python modules, the loading command is :

    from openturns import *

Otherwise, if some functionalities of the openturns python module might overload some functionalities coming from other python modules, it is preferable to launch the command :

    import openturns

In that second case, each call to an openturns type must be accompagnied by the prefix openturns. For example, to create a NumericalPoint of dimension 2, the command is myNumericalPoint = openturns.NumericalPoint(2).

In order to visualize graphics through the TUI, it is necessary to import the functionality View from the openturns.viewer module, thanks to the command :

    from openturns.viewer import View

The command :

    dir()

gives a general overview of the whole objects proposed by the openturns python library.

If you want to remove the welcome message that shows the current OpenTURNS version, you can either add the –silent command line option:

  python myScript.py --silent

or set the OPENTURNS_PYTHON_SILENT environment variable to some non empty value, e.g.

  export OPENTURNS_PYTHON_SILENT=Y

  python myScript.py

You can disable the thread-interrupt handler when using ipython by doing:

  export OPENTURNS_PYTHON_NO_INTERRUPT=Y

  ipython

Note that you won't be able to cancel long calculuses threads for example.

Verbosity level of the OpenTURNS platform

It is possible to specify the verbosity level of the OpenTURNS platform, through the object Log which contains the internal following variables :

  • Log.DBG to catch the messages related the level debug,

  • Log.WRAPPER to catch the messages related to the wrapper,

  • Log.INFO to catch the messages related to the platform information,

  • Log.USER to catch the messages defined by the User,

  • Log.WARN to catch the messages related to warnings,

  • Log.ERROR to catch the messages related to errors.

By default, the OpenTURNS platform shows all the messages related to the levels DBG, WARN and ERROR.

It is possible to change it by the command Log.Show(). For example to catch the messages related to the level debug, the warnings and information, the command is :

    Log.Show(Log.DBG + Log.WARN + Log.INFO)

In order to catch all the possible messages (highest verbosity level), the command is :

    Log.Show(Log.ALL)

In order to catch no message (lowest verbosity level), the command is :

    Log.Show(Log.NONE)

Some useful general commands

help command

The command help gives detailed information on each object of the openturns python library. For example, to get information on the object NumericalPoint, the command is :

    help(NumericalPoint)

or

    help(openturns.NumericalPoint)

according to the way the openturns python module has been loaded.

In order to quit the help document, tape the key q.

Styles in LOG messages

It is possible to set the color of the LOG messages according to the severity level of the log information, using the TTY class. For example, to color the DBG messages in red, the command is :

    Log.SetColor(Log.DBG, TTY.REDFG)

Colors are also available through codes. For example, the bold red color REDBG is coded by 13. To get all the possible colors and the association colors / codes, use the command :

    help(TTY)

Then to print a message in a specific style, associated to the code N, use the command :

    print TTY.GetColor(N), 'my message in style code'

In order to inhibit any future change of style, use the command :

    TTY.ShowColors('false')

and to make it possible again, use the command :

    TTY.ShowColors('true')

By default, it is possible to change the messages style.

List of methods

If myObject is one instance of an openturns object, then the command :

    myObject.[TAB]

lists all the methods proposed by the object myObject.

More generally, to list all the methods proposed by the NumericalMathFunction object, type the command :

    NumericalMathFunction.[TAB]

Automatic completion

In order to have some automatic completion of the openturns objects and their methods, it is necessary to type the following command in the current python session :

    import readline     import rlcompleter     readline.parse_and_bind("tab: complete")

These commands may be written in the file .pythonrc.py put in the root repertory $HOME: it will be automatically taken into account for current python sessions.

Then, in order to complete and list all the openturns objects which begin by Num, the command is :

    Num[TAB]

where [TAB] is the Tabulation key.

Manipulation of a NumericalSample

To get the value value of the (j+1)-th component of (i+1)-th point of the NumericalSample myNumSample, type the following command :

    value = myNumSample[i,j]

To set the value myValue of the (j+1)-th component of (i+1)-th point of the NumericalSample myNumSample, type the following command :

    myNumSample[i,j] = myValue

System calls for Windows Users

For some services, OpenTURNS makes system calls (for example graph production using R or evaluation of a generic wrapper) which, under Windows, open a console window which might be really annoying.

It is possible to swith from the standard system calls (system()) to a Windows specific system calls (CreateProcess()) that does not open a console windows. The command is :

    Os.EnableCreateProcess()

Yet some Users have reported some strange behavior (currently under investigation) when using the new system calls : OpenTURNS freezes. You can check whether the command is active with :

    Os.IsCreateProcessEnabled()

and, in that case, come back to the standard system calls writting :

    Os.DisableCreateProcess()

Furthermore, it is possible to make a shell call using (for example with the sell command : shell) :

    Os.ExecuteCommand('ls')

Link with other python standards

Many OpenTURNS object act like python ones, so they can be safely included in algorithms or passed as function parameters like any other python object.

The table Tab.(1) gives all the conversion possibilities between OpenTURNS objects and python or scipy ones.

        from      to            list   tuple   array  
NumericalPoint   ×   ×   ×  
NumericalSample   ×   ×   ×  
Matrix   –   –   ×  
SquareMatrix   –   –   ×  
SymmetricMatrix   –   –   ×  
CovarianceMatrix   –   –   ×  
CorrelationMatrix   –   –   ×  
Tensor   –   –   ×  
SymmetricTensor   –   –   ×  
ComplexMatrix   –   –   ×  
SquareComplexMatrix   –   –   ×  
HermitianMatrix   –   –   ×  
TriangularComplexMatrix   –   –   ×  
NumericalScalarCollection   ×   ×   ×  
Indices   ×   ×   ×[1]  
BoolCollection   ×   ×   ×[2]  
UnsignedLongCollection   ×   ×   ×[3]  
NumericalPointCollection   ×   ×   ×[4]  
Conversions of OpenTURNS objects into python/scipy ones. A × means that the conversion works, a – that it does not work and an empty cell means that no conversion is expected.
        to      from            list   tuple   array  
NumericalPoint   ×   ×   ×  
NumericalSample   ×   ×   ×  
Matrix   –   –   ×  
SquareMatrix   –   –   ×  
SymmetricMatrix   –   –   ×  
CovarianceMatrix   –   –   ×  
CorrelationMatrix   –   –   ×  
Tensor   –   –   ×  
SymmetricTensor   –   –   ×  
ComplexMatrix   –   –   ×  
SquareComplexMatrix   –   –   ×  
HermitianMatrix   –   –   ×  
TriangularComplexMatrix   –   –   ×  
NumericalScalarCollection   ×   ×   ×  
Indices   ×   ×   –  
BoolCollection   ×   ×   –  
UnsignedLongCollection   ×   ×   –  
NumericalPointCollection   ×   ×   ×  
Conversions of OpenTURNS objects into python/scipy ones. A × means that the conversion works, a – that it does not work and an empty cell means that no conversion is expected.
Table 1

For example, the NumericalPoint acts as a sequence object (aka, a list or a tuple).

It can be defined a NumericalPoint from a python list, as follows:

    point = NumericalPoint( [1.1, 2.2, 3.3, 4.4] )

or from a python tuple, as follows:

    point2 = NumericalPoint( (1.1, 2.2, 3.3, 4.4) )

It can be printed:

    print point     print repr( point )     print str( point )

or iterated:

    l = len( point )     for x in point:     print x

The NumericalSample acts the same way. It can be define from a python list, as follows:

    point = NumericalSample( [[1., 2.], [3., 4.], [5., 6.]])

which represents the sample (1,2),(3,4),5,6).

In fact any Collection object is python-aware.

Moreover, as listed in the previous table, some OpenTURNS types can be converted from/to the numpy array type.

Here is how to build a NumericalSample from a numpy array:

    import numpy as np     a0 = np.array( ((1.,2.,3.),(4.,5.,6)) )     n0 = NumericalSample( a0 )

and how to convert it back to array:

    a1 = np.array( n0 )

As we can see the OpenTURNS type to/from numpy array type is made easily by simpy calling the constructor of the desired type.

Another convenient feature is that the tuple/list/array types are allowed when calling every method that requires a NumericalPoint, NumericalSample, Indices or Description object instead of explicitely creating an object of the required type and setting its content.

For example when creating a NumericalMathFunction from variables and formulas using sequences of strings instead of Description objects:

    myFunction = NumericalMathFunction( np.array(('x0','x1')), ['y0','y1'], ('x0+x1','x0-x1') )

Another quick example for extracting the marginals of a Distribution object using a tuple of integers instead of a Indices object:

    distribution = ComposedDistribution(...)     myMarginal = distribution.getMarginal( (1,3) )


 
Table of contents
Probabilistic input vector modelisation