From COSSAN Wiki
Jump to: navigation, search
Outdated.png This article's factual accuracy may be compromised because of out-of-date information. Please help improve the article by updating it.
This description need to be updated

The class LocalFiniteDifferences is used to estimates the relative importance of the input factors of a generic function by means of the finite differences.
It is a local sensitivity method and it can be used to estimate the Gradient or the relative importance measure of the input factor.


The gradient of a scalar function f(x1, x2, x3, ..., xn) is denoted ∇f or \vec{\nabla} f where ∇ (the nabla symbol) denotes the vector differential operator. The gradient of a generic function f(\cdot) is defined as: 

(\nabla f(x))\cdot \mathbf{v} = D_{\mathbf v}f(x).

where x_i is the input factor; h the perturbation along the i direction.

In a rectangular coordinate system, the gradient is the vector field whose components are the partial derivatives of f:

 \nabla f  = \frac{\partial f}{\partial x_1 }\mathbf{e}_1 + \cdots + \frac{\partial f}{\partial x_n }\mathbf{e}_n

where the ei are the orthogonal unit vectors pointing in the coordinate directions. When a function also depends on a parameter such as time, the gradient often refers simply to the vector of its spatial derivatives only. The partial derivatives are computed by means of the finite difference methods:

 \frac{\partial{f(x)}}{\partial x_i} = \lim_{h\to0} \frac{f(x+h) - f(x)}{h} .

Relative importance

The relative importance is defined as: 

 S^{\sigma}_i(x) = \frac{\sigma_i}{\sigma_Y} \lim_{h\to0} \frac{f(x+h) - f(x)}{h} .

where \sigma_i and \sigma_Y are the standard deviation of the input factor i and the output Y, respectively.

Input Arguments

Default value
Xtarget Cossan Object yes (Engine) empty Define the object containing the quantity of interest
CXtarget cell array of Cossan object yes (GUI) empty Define the object containing the quantity of interest
Coutputname cell array no Cooutput name defined by the Xtarget object
Define the name of the quantity of interest (Required if the Xtarget contains more then 1 output name)
LperformanceFunction logical no false If is true only the sensitivity analysis respect to the performance function is computed
CnamesRandomVariable Cell of string yes if VreferencePoint is provided empty Define the name of the RandomVariable associated to the value passed in the VreferencePoint field
Double no mean values of the Input factors
Define the point where the gradient is estimated
FunctionValue Double no empty If the Samples object and the corresponding FunctionValues are passed the method uses these values as a reference point without re-evaluating the function
Xsamples Samples object no (Engine) empty
Samples object used to define the reference point. It overwrite the VreferencePoint.  It can contain only 1 sample
CXsamples cell array of Cossan object no (GUI) empty Samples object used to define the reference point. It overwrite the VreferencePoint.   It can contain only 1 sample
perturbation Double no 1e-4 Define the distance between samples (h). This value represents the fraction of the standard deviation used to perturbed the random variables.

Bulbgraph.png perturbation values
When the gradient of a 3rd-party solver is computed a perturbation value greater than 1e-2 is suggested.

Output Arguments

The method returns a @LocalSensitivityMeasures object or a @Gradient object as a output argument. As a optional output argument this method returns a @SimulationOutput object of the evaluated model.


The following methods are available for the object LocalFiniteDifferences:


Xls=Sensitivity.LocalFiniteDifferences('Xtarget',ModelObject,'CoutputName',{'myQuantityOfInterest'},'perturbation',1e-4,'VreferencePoint',[0 0 1 0]);

where Xls is a @LocalSensitivityMeasures object.

See Also