GaussLPQuadrature

class GaussLPQuadrature(*args)

Gauss-LP quadrature rule builder.

Warning

This class is experimental and likely to be modified in future releases. To use it, import the openturns.experimental submodule.

Builds a quadrature rule integrating a finite set of scalar functions against a measure. The builder is configured with the functions whose moments are reproduced, the measure against which they are integrated and, optionally, a sample of anchor nodes which constrain the rule. The quadrature reproduces the moments of the first n functions up to the requested accuracy.

The functions do not need to be orthogonal, nor orthonormal, with respect to the measure, and they do not need to be orthogonal with respect to any other distribution either. The Gauss-LP algorithm only requires their moments against the integration measure to be finite. Orthogonality is merely a convenience: it makes the target moments equal to 0 or 1 and usually improves the conditioning of the linear program. For a general collection, the moments are first estimated with the measure-adapted quadrature rule described below, and the linear program then finds nodes and positive weights reproducing these moments. The functions should be linearly independent for the moment constraints to be informative: a redundant function does not add information and can make the linear program singular.

The anchor nodes are a candidate set which is used strictly: every retained anchor has a positive weight in the returned rule. Duplicate anchors are removed with a warning, and an anchor whose target probability density function is not positive raises an exception. When the number of anchors is at least the number of requested functions, the builder first tries to reproduce the moments with the anchors alone: if it succeeds, no node is added and the returned nodes are a subset of the anchors. Otherwise all anchors are forced into the rule and the builder adds new nodes to complete the moment constraints.

The algorithm proceeds by:

  1. Computing the moments of the functions with a measure-adapted quadrature rule: an independent tensor Gauss product rule, then, when the standard space is standard normal, a Gauss-Hermite product rule transported through the inverse iso-probabilistic transformation, then a Gauss-Legendre rule on the numerical range with the density folded into the weights.

  2. Drawing candidate points uniformly over the numerical range of the measure, independently of its mass, so that the candidates span the support rather than concentrate where the density is large. For an unbounded range, the infinite components are replaced by the extreme coordinates of the measure-adapted rule. The number of candidates is \max(n \alpha_S, n + \delta), where \alpha_S is GaussLPQuadrature-AlphaS and \delta is GaussLPQuadrature-Margin.

  3. Solving linear programs to find a sparse set of nodes with positive weights. When there are at least n anchors, a minimum-weight program is first solved on the anchors alone; a feasible solution gives a rule without any added node. Otherwise, a first program maximizes the smallest anchor weight, then a minimum-weight program is solved with the anchor weights bounded from below by this positive optimum. When the sampled candidates cannot reproduce the moments, a measure-adapted tensor rule of roughly n nodes is used as an additional candidate set; without anchors it becomes the starting rule directly.

  4. Following the greedy clustering path, which merges the least weighted added node with its nearest neighbour until a target size is reached, from the smallest rule up to the largest starting rule. The latter has at most n nodes unless the anchors already impose more than n nodes. The anchors are kept by identity and are never clustered: only the added nodes take part in the condensation.

  5. Local refinement via TNC optimization of each rule along the clustering path, skipped when the starting rule already meets the tolerance, with an explicit fallback to the clustered rule if the optimization fails. The first rule meeting the tolerance is returned, so that the number of nodes is the smallest one found on the path. The residual gradient is analytic. The anchor coordinates are fixed and the anchor weights stay positive during the refinement.

The number of nodes is therefore an output of the algorithm, not a prescribed size. It is at most n when there are fewer than n anchors. Use buildRule() to obtain an immutable GaussLPQuadratureRule that can be passed to ExperimentIntegration or to any API expecting a weighted experiment.

A dependent elliptical measure whose standard distribution is not the standard normal distribution is rejected: the numerical range truncates its heavy tails, so the Gauss-Legendre fallback cannot reproduce the moments.

Note

The linear program requires HiGHS support. When OpenTURNS is built without HiGHS, the linear program fails: without anchors, the builder falls back to a refined measure-adapted tensor rule and emits a warning; with anchors, build() and buildRule() raise an exception.

The Gauss-LP approach was introduced by [ryu2015] and extended to the multivariate setting with a greedy clustering strategy by [jakeman2018].

Parameters:
functionssequence of Function

Scalar functions whose moments are reproduced. The quadrature reproduces the moments of the first n functions against measure up to the refinement tolerance. The functions do not need to be orthogonal with respect to measure.

measureDistribution

Integration measure.

anchors2-d sequence of float

Optional anchor nodes used as a candidate pool. Duplicates are removed, every retained anchor has a positive weight in the rule and every anchor must have a positive target PDF.

Methods

build(n)

Build a quadrature rule.

buildRule(n)

Build an immutable quadrature rule.

getAnchors()

Accessor to the anchor nodes.

getClassName()

Accessor to the object's name.

getFunctionsCollection()

Accessor to the functions used by the builder.

getMeasure()

Accessor to the integration measure.

getName()

Accessor to the object's name.

getSize()

Accessor to the number of functions used by the builder.

hasName()

Test if the object is named.

setAnchors(anchors)

Set the anchor nodes.

setMeasureAndFunctions(measure, functions)

Accessor to the functions and measure used by the builder.

setName(name)

Accessor to the object's name.

Notes

The following ResourceMap keys are used:

Key

Type

Default value

Description

GaussLPQuadrature-AlphaS

UnsignedInteger

100

Multiplier for the number of LP candidate points.

GaussLPQuadrature-Margin

UnsignedInteger

10

Minimum number of candidate points beyond the number of functions. It is a heuristic ensuring that small values of GaussLPQuadrature-AlphaS still give the linear program more columns than moment constraints.

GaussLPQuadrature-Ngauss

UnsignedInteger

100

Requested order of the measure-adapted rule used for the moments.

GaussLPQuadrature-MaximumTensorNodes

UnsignedInteger

1000000

Maximum number of nodes of the tensor rule used for the moments. The marginal order is reduced when the full tensor product would exceed this budget, and the rule is rejected when the budget cannot even hold the order-2 tensor product.

GaussLPQuadrature-Epsilon

Scalar

1.0e-5

Tolerance on the norm of the quadrature residual; a warning is emitted above it.

GaussLPQuadrature-ClusterPath

Bool

True

Refine the rules obtained along the greedy clustering path from one node up to the largest rule, and stop at the first rule meeting GaussLPQuadrature-Epsilon. When False, only the largest rule is refined.

GaussLPQuadrature-MaximumAbsoluteError

Scalar

1.0e-12

Absolute error tolerance of the local refinement, superseding OptimizationAlgorithm-DefaultMaximumAbsoluteError.

GaussLPQuadrature-MaximumRelativeError

Scalar

1.0e-12

Relative error tolerance of the local refinement, superseding OptimizationAlgorithm-DefaultMaximumRelativeError.

GaussLPQuadrature-MaximumObjectiveError

Scalar

1.0e-12

Objective error tolerance of the local refinement, superseding OptimizationAlgorithm-DefaultMaximumResidualError.

GaussLPQuadrature-MaximumConstraintError

Scalar

1.0e-12

Constraint error tolerance of the linear programming solve and of the local refinement, superseding OptimizationAlgorithm-DefaultMaximumConstraintError.

GaussLPQuadrature-Solver

String

choose

HiGHS solver used for the linear programming solve.

GaussLPQuadrature-FallbackSolver

String

ipm

HiGHS solver used when the first linear programming solve fails; an empty value disables the retry.

Examples

>>> import openturns as ot
>>> import openturns.experimental as otexp
>>> measure = ot.JointDistribution([ot.Uniform(0.0, 1.0)] * 2)
>>> functions = [ot.SymbolicFunction(['x', 'y'], [formula])
...              for formula in ['1.0', 'x', 'y', 'x * y']]
>>> quad = otexp.GaussLPQuadrature(functions, measure)
>>> nodes, weights = quad.build(3)
>>> rule = quad.buildRule(3)

A known three-point rule can be reused as anchors: when the anchors alone reproduce the moments, the builder adds no node.

>>> measure1d = ot.Uniform(2.0, 4.0)
>>> functions1d = [ot.SymbolicFunction('x', formula)
...                for formula in ['1', 'x', 'x^2']]
>>> anchors = ot.Sample([[3.0 - (3.0 / 5.0) ** 0.5],
...                      [3.0],
...                      [3.0 + (3.0 / 5.0) ** 0.5]])
>>> anchored = otexp.GaussLPQuadrature(functions1d, measure1d, anchors)
>>> anchored.getAnchors().getSize()
3
>>> anchoredNodes, anchoredWeights = anchored.build(3)
__init__(*args)
build(n)

Build a quadrature rule.

Parameters:
nint

Number of functions whose moments are reproduced. It must be positive and must not exceed getSize().

Returns:
nodesSample

The quadrature nodes. Their number is an output of the algorithm: it is at most n when there are fewer than n anchors. When a rule supported by the anchors alone reproduces the moments, no node is added and the nodes are a subset of the anchors. Otherwise all the anchors are the first nodes, in input order, followed by the added nodes. When GaussLPQuadrature-ClusterPath is True, the smallest rule found along the greedy clustering path that meets the residual tolerance is returned; otherwise the full clustered support is refined.

weightsPoint

The quadrature weights, returned in the second output argument. They have one entry per node and are positive.

buildRule(n)

Build an immutable quadrature rule.

Parameters:
nint

Number of functions whose moments are reproduced. It must be positive and must not exceed getSize().

Returns:
ruleGaussLPQuadratureRule

The immutable weighted experiment holding the nodes, the weights and the measure.

getAnchors()

Accessor to the anchor nodes.

Returns:
anchorsSample

The anchors retained by the builder, with duplicates removed.

getClassName()

Accessor to the object’s name.

Returns:
class_namestr

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

getFunctionsCollection()

Accessor to the functions used by the builder.

Returns:
functionsFunctionCollection

The scalar functions whose moments are reproduced.

getMeasure()

Accessor to the integration measure.

Returns:
measureDistribution

Measure against which the moments are computed.

getName()

Accessor to the object’s name.

Returns:
namestr

The name of the object.

getSize()

Accessor to the number of functions used by the builder.

Returns:
sizeint

Number of functions whose moments can be reproduced.

hasName()

Test if the object is named.

Returns:
hasNamebool

True if the name is not empty.

setAnchors(anchors)

Set the anchor nodes.

The anchors form a candidate pool used by build() and buildRule(): every retained anchor has a positive weight in the rule. When the anchors alone reproduce the moments, the rule is supported by a subset of them and no node is added. Duplicate anchors are removed with a warning, and every retained anchor must have a positive target PDF when the measure is already set. Setting an empty sample removes all the anchors.

Parameters:
anchors2-d sequence of float

Anchor nodes, dimensioned like the integration measure.

setMeasureAndFunctions(measure, functions)

Accessor to the functions and measure used by the builder.

The current anchors are preserved and revalidated against the new measure: an anchor outside the support of the new measure raises an exception and leaves the builder unchanged.

Parameters:
measureDistribution

Integration measure.

functionssequence of Function

Non-empty collection of scalar functions dimensioned like measure. The functions do not need to be orthogonal with respect to measure.

setName(name)

Accessor to the object’s name.

Parameters:
namestr

The name of the object.

Examples using the class

Build a sparse quadrature rule with the Gauss-LP algorithm

Build a sparse quadrature rule with the Gauss-LP algorithm

Orthonormalize a finite set of functions on a multivariate domain

Orthonormalize a finite set of functions on a multivariate domain