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.experimentalsubmodule.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
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:
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.
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
, where
is
GaussLPQuadrature-AlphaSandis
GaussLPQuadrature-Margin.Solving linear programs to find a sparse set of nodes with positive weights. When there are at least
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
nodes is used as an additional candidate set; without anchors it becomes the starting rule directly.
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
nodes unless the anchors already impose more than
nodes. The anchors are kept by identity and are never clustered: only the added nodes take part in the condensation.
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
when there are fewer than
anchors. Use
buildRule()to obtain an immutableGaussLPQuadratureRulethat can be passed toExperimentIntegrationor 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()andbuildRule()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
nfunctions against measure up to the refinement tolerance. The functions do not need to be orthogonal with respect to measure.- measure
Distribution 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.
- functionssequence of
Methods
build(n)Build a quadrature rule.
buildRule(n)Build an immutable quadrature rule.
Accessor to the anchor nodes.
Accessor to the object's name.
Accessor to the functions used by the builder.
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
ResourceMapkeys are used:Key
Type
Default value
Description
GaussLPQuadrature-AlphaSUnsignedInteger100Multiplier for the number of LP candidate points.
GaussLPQuadrature-MarginUnsignedInteger10Minimum number of candidate points beyond the number of functions. It is a heuristic ensuring that small values of
GaussLPQuadrature-AlphaSstill give the linear program more columns than moment constraints.GaussLPQuadrature-NgaussUnsignedInteger100Requested order of the measure-adapted rule used for the moments.
GaussLPQuadrature-MaximumTensorNodesUnsignedInteger1000000Maximum 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-EpsilonScalar1.0e-5Tolerance on the norm of the quadrature residual; a warning is emitted above it.
GaussLPQuadrature-ClusterPathBoolTrueRefine 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. WhenFalse, only the largest rule is refined.GaussLPQuadrature-MaximumAbsoluteErrorScalar1.0e-12Absolute error tolerance of the local refinement, superseding
OptimizationAlgorithm-DefaultMaximumAbsoluteError.GaussLPQuadrature-MaximumRelativeErrorScalar1.0e-12Relative error tolerance of the local refinement, superseding
OptimizationAlgorithm-DefaultMaximumRelativeError.GaussLPQuadrature-MaximumObjectiveErrorScalar1.0e-12Objective error tolerance of the local refinement, superseding
OptimizationAlgorithm-DefaultMaximumResidualError.GaussLPQuadrature-MaximumConstraintErrorScalar1.0e-12Constraint error tolerance of the linear programming solve and of the local refinement, superseding
OptimizationAlgorithm-DefaultMaximumConstraintError.GaussLPQuadrature-SolverStringchooseHiGHS solver used for the linear programming solve.
GaussLPQuadrature-FallbackSolverStringipmHiGHS 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:
- nodes
Sample The quadrature nodes. Their number is an output of the algorithm: it is at most
nwhen there are fewer thannanchors. 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. WhenGaussLPQuadrature-ClusterPathisTrue, the smallest rule found along the greedy clustering path that meets the residual tolerance is returned; otherwise the full clustered support is refined.- weights
Point The quadrature weights, returned in the second output argument. They have one entry per node and are positive.
- nodes
- 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:
- rule
GaussLPQuadratureRule The immutable weighted experiment holding the nodes, the weights and the measure.
- rule
- getAnchors()¶
Accessor to the anchor nodes.
- Returns:
- anchors
Sample The anchors retained by the builder, with duplicates removed.
- anchors
- 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:
- functions
FunctionCollection The scalar functions whose moments are reproduced.
- functions
- getMeasure()¶
Accessor to the integration measure.
- Returns:
- measure
Distribution Measure against which the moments are computed.
- measure
- 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()andbuildRule(): 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:
- measure
Distribution 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.
- 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
Orthonormalize a finite set of functions on a multivariate domain
OpenTURNS