LinearCombinationFunction¶

(Source code, svg)

class LinearCombinationFunction(*args)¶

Linear combination of functions.

Allows one to create a function which is the linear combination of functions with scalar weights.

$functionCollection = (f_1, \hdots, f_N)$ where $\forall 1 \leq i \leq N, \, f_i: \Rset^n \rightarrow \Rset^{p}$ and $scalarCoefficientColl = (c_1, \hdots, c_N) \in \Rset^N$ then the linear combination is:

$linComb \left|\begin{array}{rcl} \Rset^n & \rightarrow & \Rset^{p} \\ \vect{X} & \mapsto & \displaystyle \sum_{i=1}^N c_i f_i (\vect{X}) \end{array}\right.$

Parameters:

functionCollectionsequence of Function: Collection of functions to sum.
scalarCoefficientCollsequence of float: Collection of scalar weights.

Methods

`draw`(*args)	Draw the output of function as a `Graph`.
`drawCrossCuts`(*args)	Draw the 2D and 1D cross cuts of a 1D output function as a `GridLayout`.
`getCallsNumber`()	Accessor to the number of direct calls to the function.
`getClassName`()	Accessor to the object's name.
`getDescription`()	Accessor to the description of the inputs and outputs.
`getEvaluation`()	Accessor to the evaluation function.
`getEvaluationCallsNumber`()	Accessor to the number of times the evaluation of the function has been called.
`getGradient`()	Accessor to the gradient function.
`getGradientCallsNumber`()	Accessor to the number of times the gradient of the function has been called.
`getHessian`()	Accessor to the hessian function.
`getHessianCallsNumber`()	Accessor to the number of times the hessian of the function has been called.
`getId`()	Accessor to the object's id.
`getImplementation`()	Accessor to the underlying implementation.
`getInputDescription`()	Accessor to the description of the input vector.
`getInputDimension`()	Accessor to the dimension of the input vector.
`getMarginal`(*args)	Accessor to marginal.
`getName`()	Accessor to the object's name.
`getOutputDescription`()	Accessor to the description of the output vector.
`getOutputDimension`()	Accessor to the number of the outputs.
`getParameter`()	Accessor to the parameter values.
`getParameterDescription`()	Accessor to the parameter description.
`getParameterDimension`()	Accessor to the dimension of the parameter.
`gradient`(inP)	Return the Jacobian transposed matrix of the function at a point.
`hessian`(inP)	Return the hessian of the function at a point.
`isLinear`()	Accessor to the linearity of the function.
`isLinearlyDependent`(index)	Accessor to the linearity of the function with regard to a specific variable.
`parameterGradient`(inP)	Accessor to the gradient against the parameter.
`setDescription`(description)	Accessor to the description of the inputs and outputs.
`setEvaluation`(evaluation)	Accessor to the evaluation function.
`setGradient`(gradient)	Accessor to the gradient function.
`setHessian`(hessian)	Accessor to the hessian function.
`setInputDescription`(inputDescription)	Accessor to the description of the input vector.
`setName`(name)	Accessor to the object's name.
`setOutputDescription`(inputDescription)	Accessor to the description of the output vector.
`setParameter`(parameter)	Accessor to the parameter values.
`setParameterDescription`(description)	Accessor to the parameter description.
`setStopCallback`(callBack[, state])	Set up a stop callback.

Examples

>>> import openturns as ot
>>> f1 = ot.SymbolicFunction(['x'], ['sin(x)'])
>>> f2 = ot.SymbolicFunction(['x'], ['x'])
>>> f3 = ot.SymbolicFunction(['x'], ['cos(x)'])
>>> f = ot.LinearCombinationFunction([f1, f2, f3], [1.0, 2.0, 3.0])

Evaluate the function:

>>> x = [1.0]
>>> y = f(x)

__init__(*args)¶

draw(*args)¶

Draw the output of function as a Graph.

Available usages:

draw(inputMarg, outputMarg, centralPoint, xiMin, xiMax, ptNb, scale)

draw(firstInputMarg, secondInputMarg, outputMarg, centralPoint, xiMin_xjMin, xiMax_xjMax, ptNbs, scale, isFilled)

draw(xiMin, xiMax, ptNb, scale)

draw(xiMin_xjMin, xiMax_xjMax, ptNbs, scale)

Parameters:

outputMarg, inputMargint, $outputMarg, inputMarg \geq 0$

outputMarg is the index of the marginal to draw as a function of the marginal with index inputMarg.

firstInputMarg, secondInputMargint, $firstInputMarg, secondInputMarg \geq 0$

In the 2D case, the marginal outputMarg is drawn as a function of the two marginals with indexes firstInputMarg and secondInputMarg.

centralPointsequence of float

Central point with dimension equal to the input dimension of the function.

xiMin, xiMaxfloat

Define the interval where the curve is plotted.

xiMin_xjMin, xiMax_xjMaxsequence of float of dimension 2.

In the 2D case, define the intervals where the curves are plotted.

ptNbint $ptNb > 0$

The number of points to draw the curves.

ptNbslist of int of dimension 2 $ptNbs_k > 0, k=1,2$

The number of points to draw the contour in the 2D case.

scalebool

scale indicates whether the logarithmic scale is used either for one or both axes:

ot.GraphImplementation.NONE or 0: no log scale is used,
ot.GraphImplementation.LOGX or 1: log scale is used only for horizontal data,
ot.GraphImplementation.LOGY or 2: log scale is used only for vertical data,
ot.GraphImplementation.LOGXY or 3: log scale is used for both data.

isFilledbool

isFilled indicates whether the contour graph is filled or not

Notes

We note $f: \Rset^n \rightarrow \Rset^p$ where $\vect{x} = (x_1, \dots, x_n)$ and $f(\vect{x}) = (f_1(\vect{x}), \dots, f_p(\vect{x}))$ , with $n\geq 1$ and $p\geq 1$ .

In the first usage:

Draws graph of the given 1D outputMarg marginal $f_k: \Rset^n \rightarrow \Rset$ as a function of the given 1D inputMarg marginal with respect to the variation of $x_i$ in the interval $[x_i^{min}, x_i^{max}]$ , when all the other components of $\vect{x}$ are fixed to the corresponding components of the centralPoint $\vect{c}$ . Then OpenTURNS draws the graph:

$y = f_k^{(i)}(s)$

for any $s \in [x_i^{min}, x_i^{max}]$ where $f_k^{(i)}(s)$ is defined by the equation:

$f_k^{(i)}(s) = f_k(c_1, \dots, c_{i-1}, s, c_{i+1} \dots, c_n).$

In the second usage:

Draws the iso-curves of the given outputMarg marginal $f_k$ as a function of the given 2D firstInputMarg and secondInputMarg marginals with respect to the variation of $(x_i, x_j)$ in the interval $[x_i^{min}, x_i^{max}] \times [x_j^{min}, x_j^{max}]$ , when all the other components of $\vect{x}$ are fixed to the corresponding components of the centralPoint $\vect{c}$ . Then OpenTURNS draws the graph:

$y = f_k^{(i,j)}(s, t)$

for any $(s, t) \in [x_i^{min}, x_i^{max}] \times [x_j^{min}, x_j^{max}]$ where $f_k^{(i,j)}$ is defined by the equation:

$f_k^{(i,j)}(s,t) = f_k(c_1, \dots, c_{i-1}, s, c_{i+1}, \dots, c_{j-1}, t, c_{j+1} \dots, c_n).$

In the third usage:

The same as the first usage but only for function $f: \Rset \rightarrow \Rset$ .

In the fourth usage:

The same as the second usage but only for function $f: \Rset^2 \rightarrow \Rset$ .

Examples

>>> import openturns as ot
>>> from openturns.viewer import View
>>> f = ot.SymbolicFunction('x', 'sin(2*pi_*x)*exp(-x^2/2)')
>>> graph = f.draw(-1.2, 1.2, 100)
>>> View(graph).show()

drawCrossCuts(*args)¶

Draw the 2D and 1D cross cuts of a 1D output function as a GridLayout.

Parameters:

centralPointlist of float: Central point with dimension equal to the input dimension of the function.
xMin, xMaxlist of float: Define the interval where the curve is plotted.
pointNumberIndices: The number of points to draw the contours and the curves.
withMonoDimensionalCutsbool, optional: withMonoDimensionalCuts indicates whether the mono dimension cuts are drawn or not Default value is specified in the CrossCuts-DefaultWithMonoDimensionalCuts ResourceMap key.
isFilledbool, optional: isFilled indicates whether the contour graphs are filled or not Default value is specified in the Contour-DefaultIsFilled ResourceMap key
vMin, vMaxfloat, optional: Define the interval used to build the color map for the contours If not specified, these values are computed to best fit the graphs. Either specify both values or do not specify any.

Notes

We note $f: \Rset^n \rightarrow \Rset^p$ where $\vect{x} = (x_1, \dots, x_n)$ and $f(\vect{x}) = (f_1(\vect{x}), \dots, f_p(\vect{x}))$ , with $n\geq 1$ and $p\geq 1$ .

In all usages, draw the 1D and 2D cross cuts of $f_k: \Rset^n \rightarrow \Rset$ as a function of all input coordinates for 1D cuts and all couples of coordinates for 2D cuts. Variable coordinates $x_i$ are sampled regularly using $ptNb[i]$ points in the interval $[x_i^{min}, x_i^{max}]$ , when all the other components of $\vect{x}$ are fixed to the corresponding components of the centralPoint $\vect{c}$ . In the first usage, vMin and vMax are evaluated as the min and max of all samples of the function value calculated in all cross cuts performed.

For 1D cross cuts the graph shows:

$y = f_k^{(i)}(s)$

for any $s \in [x_i^{min}, x_i^{max}]$ where $f_k^{(i)}(s)$ is defined by the equation:

$f_k^{(i)}(s) = f_k(c_1, \dots, c_{i-1}, s, c_{i+1} \dots, c_n).$

For 2D cross cuts:

$y = f_k^{(i,j)}(s, t)$

for any $(s, t) \in [x_i^{min}, x_i^{max}] \times [x_j^{min}, x_j^{max}]$ where $f_k^{(i,j)}$ is defined by the equation:

$f_k^{(i,j)}(s,t) = f_k(c_1, \dots, c_{i-1}, s, c_{i+1}, \dots, c_{j-1}, t, c_{j+1} \dots, c_n).$

Examples

>>> import openturns as ot
>>> from openturns.viewer import View
>>> f = ot.SymbolicFunction(['x0', 'x1', 'x2'], ['sin(1*pi_*x0) + x1 - x2 ^ 2'])
>>> grid = f.drawCrossCuts([0., 0., 0.], [-3., -3, -3], [3, 3, 3], [100, 20, 20], True, True)
>>> View(grid).show()

getCallsNumber()¶

Accessor to the number of direct calls to the function.

Returns:

calls_numberint: Integer that counts the number of times the function has been called directly through the () operator.

getClassName()¶

Accessor to the object’s name.

Returns:

class_namestr: The object class name (object.__class__.__name__).

getDescription()¶

Accessor to the description of the inputs and outputs.

Returns:

descriptionDescription: Description of the inputs and the outputs.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                         ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getDescription())
[x1,x2,y0]

getEvaluation()¶

Accessor to the evaluation function.

Returns:

evaluationEvaluationImplementation: The evaluation function.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                         ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getEvaluation())
[x1,x2]->[2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6]

getEvaluationCallsNumber()¶

Accessor to the number of times the evaluation of the function has been called.

Returns:

evaluation_calls_numberint: Integer that counts the number of times the evaluation of the function has been called since its creation. This may include indirect calls via finite-difference gradient or Hessian.

getGradient()¶

Accessor to the gradient function.

Returns:

gradientGradientImplementation: The gradient function.

Examples

To get the gradient formulas when the function is a SymbolicFunction. The indices are $(i,j)$ . The corresponding formula is $\left( \dfrac{\partial f_j(\vect{x})}{\partial x_i} \right)$ . >>> import openturns as ot >>> f = ot.SymbolicFunction([‘x1’, ‘x2’], … [‘2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6’]) >>> formula_deriv_x1 = f.getGradient().getImplementation().getFormula(0,0) >>> formula_deriv_x2 = f.getGradient().getImplementation().getFormula(1,0)

getGradientCallsNumber()¶

Accessor to the number of times the gradient of the function has been called.

Returns:

gradient_calls_numberint: Integer that counts the number of times the gradient of the Function has been called since its creation. Note that if the gradient is implemented by a finite difference method, the gradient calls number is equal to 0 and the different calls are counted in the evaluation calls number.

getHessian()¶

Accessor to the hessian function.

Returns:

hessianHessianImplementation: The hessian function.

Examples

To get the hessian formulas when the function is a SymbolicFunction. The indices are $(i,j,k)$ . The corresponding formula is $\left( \dfrac{\partial^2 f_k(\vect{x})}{\partial x_i \partial x_j} \right)$ . >>> import openturns as ot >>> f = ot.SymbolicFunction([‘x1’, ‘x2’], … [‘2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6’]) >>> formula_hessian_000 = f.getHessian().getImplementation().getFormula(0,0,0) >>> formula_hessian_010 = f.getHessian().getImplementation().getFormula(0,1,0) >>> formula_hessian_110 = f.getHessian().getImplementation().getFormula(1,1,0) >>> formula_hessian_001 = f.getHessian().getImplementation().getFormula(0,0,0) >>> formula_hessian_011 = f.getHessian().getImplementation().getFormula(0,1,0) >>> formula_hessian_111 = f.getHessian().getImplementation().getFormula(1,1,0)

getHessianCallsNumber()¶

Accessor to the number of times the hessian of the function has been called.

Returns:

hessian_calls_numberint: Integer that counts the number of times the hessian of the Function has been called since its creation. Note that if the hessian is implemented by a finite difference method, the hessian calls number is equal to 0 and the different calls are counted in the evaluation calls number.

getId()¶

Accessor to the object’s id.

Returns:

idint: Internal unique identifier.

getImplementation()¶

Accessor to the underlying implementation.

Returns:

implImplementation: A copy of the underlying implementation object.

getInputDescription()¶

Accessor to the description of the input vector.

Returns:

descriptionDescription: Description of the input vector.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getInputDescription())
[x1,x2]

getInputDimension()¶

Accessor to the dimension of the input vector.

Returns:

inputDimint: Dimension of the input vector $d$ .

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getInputDimension())
2

getMarginal(*args)¶

Accessor to marginal.

Parameters:

indicesint or list of ints: Set of indices for which the marginal is extracted.

Returns:

marginalFunction: Function corresponding to either $f_i$ or $(f_i)_{i \in indices}$ , with $f:\Rset^n \rightarrow \Rset^p$ and $f=(f_0 , \dots, f_{p-1})$ .

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getOutputDescription()¶

Accessor to the description of the output vector.

Returns:

descriptionDescription: Description of the output vector.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getOutputDescription())
[y0]

getOutputDimension()¶

Accessor to the number of the outputs.

Returns:

number_outputsint: Dimension of the output vector $d'$ .

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getOutputDimension())
1

getParameter()¶

Accessor to the parameter values.

Returns:

parameterPoint: The parameter values.

getParameterDescription()¶

Accessor to the parameter description.

Returns:

parameterDescription: The parameter description.

getParameterDimension()¶

Accessor to the dimension of the parameter.

Returns:

parameterDimensionint: Dimension of the parameter.

gradient(inP)¶

Return the Jacobian transposed matrix of the function at a point.

Parameters:

pointsequence of float: Point where the Jacobian transposed matrix is calculated.

Returns:

gradientMatrix: The Jacobian transposed matrix of the function at point.

Notes

Let $f : \Rset^\inputDim \rightarrow \Rset^p$ where the $f_i$ are the components functions. Then, the gradient evaluated at $\vect{x}$ is the matrix with $\inputDim$ rows and $p$ columns defined by:

$\nabla f(\vect{x}) & = \left( \dfrac{\partial f_j(\vect{x})}{\partial x_i} \right)_{i,j} \\ & = \left( \begin{array}{lcr} \dfrac{\partial f_1(\vect{x})}{\partial x_1} & \hdots & \dfrac{\partial f_p(\vect{x})}{\partial x_1}\\ vdots & \vdots & \vdots \\ \dfrac{\partial f_1(\vect{x})}{\partial x_\inputDim} & \hdots & \dfrac{\partial f_p(\vect{x})}{\partial x_\inputDim} \end{array} \right)$

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6','x1 + x2'])
>>> print(f.gradient([3.14, 4]))
[[ 13.5345   1       ]
 [  4.00001  1       ]]

hessian(inP)¶

Return the hessian of the function at a point.

Parameters:

pointsequence of float: Point where the hessian of the function is calculated.

Returns:

hessianSymmetricTensor: Hessian of the function at point.

Notes

Let $f : \Rset^\inputDim \rightarrow \Rset^p$ where the $f_i$ are the components functions. Then, the hessian evaluated at $\vect{x}$ is a symmetric tensor with $p$ sheets, each one composed of $\inputDim$ rows and $\inputDim$ columns. The $k$ -th sheet is defined by:

$\left( \dfrac{\partial^2 f_k(\vect{x})}{\partial x_i \partial x_j} \right)_{i,j}$

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6','x1 + x2'])
>>> print(f.hessian([3.14, 4]))
sheet #0
[[ 20          -0.00637061 ]
 [ -0.00637061  0          ]]
sheet #1
[[  0           0          ]
 [  0           0          ]]

isLinear()¶

Accessor to the linearity of the function.

Returns:

linearbool: True if the function is linear, False otherwise.

isLinearlyDependent(index)¶

Accessor to the linearity of the function with regard to a specific variable.

Parameters:

indexint: The index of the variable with regard to which linearity is evaluated.

Returns:

linearbool: True if the function is linearly dependent on the specified variable, False otherwise.

parameterGradient(inP)¶

Accessor to the gradient against the parameter.

Returns:

gradientMatrix: The gradient.

setDescription(description)¶

Accessor to the description of the inputs and outputs.

Parameters:

descriptionsequence of str: Description of the inputs and the outputs.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> print(f.getDescription())
[x1,x2,y0]
>>> f.setDescription(['a','b','y'])
>>> print(f.getDescription())
[a,b,y]

setEvaluation(evaluation)¶

Accessor to the evaluation function.

Parameters:

functionEvaluationImplementation: The evaluation function.

setGradient(gradient)¶

Accessor to the gradient function.

Parameters:

gradient_functionGradientImplementation: The gradient function.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                          ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> f.setGradient(ot.CenteredFiniteDifferenceGradient(
...  ot.ResourceMap.GetAsScalar('CenteredFiniteDifferenceGradient-DefaultEpsilon'),
...  f.getEvaluation()))

setHessian(hessian)¶

Accessor to the hessian function.

Parameters:

hessian_functionHessianImplementation: The hessian function.

Examples

>>> import openturns as ot
>>> f = ot.SymbolicFunction(['x1', 'x2'],
...                         ['2 * x1^2 + x1 + 8 * x2 + 4 * cos(x1) * x2 + 6'])
>>> f.setHessian(ot.CenteredFiniteDifferenceHessian(
...  ot.ResourceMap.GetAsScalar('CenteredFiniteDifferenceHessian-DefaultEpsilon'),
...  f.getEvaluation()))