ChristoffelSubsampleExperiment

(Source code, svg)

../../_images/ChristoffelSubsampleExperiment.svg
class ChristoffelSubsampleExperiment(*args)

Christoffel subsample experiment.

Warning

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

Given an orthonormal basis of L^2(\cD, \mu) and a target size n, the experiment builds the first m basis functions and returns a weighted design of n points. The points are drawn from the Christoffel distribution, or from the determinantal point process (DPP) associated with its kernel. In the fresh mode, the weights m / k_m are the density ratios of the reference measure over the Christoffel distribution, so the weighted design is an unbiased quadrature rule for \mu. See Christoffel distribution and sampling for the theory of the Christoffel distribution, of DPPs, and of the frame certificate.

Two sizing modes are available.

By default, m = n - k is the largest dimension supplied by the basis: k = 0 with an inexhaustible basis, and k = 1, 2, \dots is tried until the basis supplies m functions. For n = m, a fresh design is an exact projection DPP of size m associated with the Christoffel kernel. For n > m, the first m points are a projection DPP and the remaining n - m points are independent draws from the ChristoffelDistribution; the design is then randomly permuted. See Determinantal point processes on the Christoffel kernel for the exact sequential DPP sampler and its cost.

When the ChristoffelSubsampleExperiment-Certified key is true, the experiment uses the certified sizing of Cohen and Dolbeault [cohendolbeault2020]: m is the largest integer with n \ge \gamma m \log(m), where \gamma is the ChristoffelSubsampleExperiment-Gamma key value, and a fresh design is n independent draws from the ChristoffelDistribution. No thinning is applied. The weighted design is checked against the frame bounds; if it misses them, the whole independent sample is redrawn, up to ChristoffelSubsampleExperiment-MaxAttempts draws. If no draw passes, the draw with the largest smallest eigenvalue of the weighted Gramian (the sharpest realized frame) is returned with a warning. This mode makes m much smaller than n and is not the default; when the key is false, m = n-k is chosen by the basis capacity as described above. See Weighted least squares and frame certificate for the certified budget and the frame condition.

This certified sizing fixes n and adapts m. It is natural when the approximation space belongs to a nested hierarchy, but not when m is fixed by the model and only n can be chosen. In that fixed-space setting the certificate gives the lower bound n \ge \gamma m \log(2m/\varepsilon) for the fixed m; the current implementation does not expose a fixed-m strategy, which is left for a future release. As a workaround, choose the target size n = \lceil \gamma m \log(m) \rceil for m \ge 2 (and n = 1 for m = 1), provided the basis supplies m functions and n \ge m. For small \gamma the formula can give n < m, in which case the certified space dimension is bounded by n; check getSpaceDimension() and increase n (or \gamma) until it is m.

When points are supplied to generateWithWeights(), an empty sample of any dimension selects the fresh path. Supplied candidates are assumed to be draws from the reference measure. If more than n points are supplied, exactly n of them are selected by exact volume sampling, with probability proportional to the determinant of the Gram matrix of their basis features; no fresh point is drawn. When n = m this selection is the projection-DPP law restricted to the pool, and when n > m it is a discrete volume-sampling law. In both cases, unlike a fresh design, the finite-pool law does not inherit the continuous Christoffel marginals, so the returned m / k_m ratios are not guaranteed unbiased quadrature weights for \mu. If exactly n points are supplied, all of them are kept with unit weights, since no Christoffel selection takes place. If fewer than n and at most m points are supplied, all of them are kept and the DPP is conditioned on their feature vectors; the remaining m - M DPP points are drawn, followed by n - m independent Christoffel points when n > m. Supplying more than m points while asking for fewer than n points is rejected, as is a set of supplied features that is not linearly independent. See Conditional DPP and volume sampling for conditional DPPs and volume sampling. In certified mode, supplied points are rejected because the certificate assumes independent Christoffel draws; only the fresh path is available.

Each design point of a fresh, conditional or volume-sampled design carries a weight proportional to m / k_m(\vect{x}_i), the density ratio of the reference measure over the Christoffel distribution. The exactly-n supplied design is the exception: it is returned unchanged with unit weights because no selection takes place. The returned weights are positive and finite: a point with a null or non-finite importance ratio is rejected instead of being returned with a zero weight.

For a Christoffel-weighted design, the implementation checks the eigenvalues of the normalized weighted design Gramian against the band [1 - \tau, 1 + \tau], where \tau is the ChristoffelSubsampleExperiment-FrameTolerance key, and warns when they are missed. In the default mode this check is advisory: it is not a certificate that the frame bounds hold. For n = m the design is square and the projection DPP has no certified frame guarantee; for n > m the extra independent Christoffel points improve the budget without making the certificate exact. In certified mode, the independent Christoffel budget n = \gamma m \log(m) is the leading-order Cohen-Dolbeault setting; the omitted \log(2/\varepsilon) factor sets the confidence level, and the realized design is checked. The draw is repeated until it passes, up to the configured attempt limit. If no draw passes, the draw with the largest smallest Gram eigenvalue is returned with a warning. The conditional quasi-optimality of the weighted least squares estimator on the frame event is analyzed in [haberstich2022]. Use computeDesignEigenvalues() when a frame diagnostic is required on a given design. See Weighted least squares and frame certificate for the frame condition and the certified budget.

Parameters:
basisOrthogonalBasis

Orthonormal basis defining the approximation space. Its embedded measure \mu must be continuous.

sizepositive int

Number n of points of the experiment.

Methods

DeduceSpaceDimension(size)

Deduce the space dimension from a target size.

computeDesignEigenvalues(sample, weights)

Eigenvalues of the weighted design Gramian.

generate()

Generate points according to the type of the experiment.

generateWithWeights(*args)

Generate the weighted design.

getClassName()

Accessor to the object's name.

getDistribution()

Accessor to the distribution.

getName()

Accessor to the object's name.

getOrthogonalBasis()

Accessor to the orthogonal basis.

getSize()

Accessor to the size of the generated sample.

getSpaceDimension()

Accessor to the space dimension deduced from the target size.

hasName()

Test if the object is named.

hasUniformWeights()

Ask whether the experiment has uniform weights.

isRandom()

Accessor to the randomness of quadrature.

setDistribution(distribution)

Accessor to the distribution.

setLevels(levels)

Accessor to the experiment nesting levels.

setName(name)

Accessor to the object's name.

setOrthogonalBasis(basis)

Accessor to the orthogonal basis.

setSize(size)

Accessor to the size of the generated sample.

Notes

A default-constructed experiment has no configured basis: call setOrthogonalBasis() (and optionally setSize()) before generating. Generation from the unconfigured default state throws.

The following ResourceMap keys are used:

  • ChristoffelSubsampleExperiment-FrameTolerance (Scalar, default: 0.5): half-width of the accepted frame eigenvalue band around 1. It must be non-negative and finite.

  • ChristoffelSubsampleExperiment-Certified (Bool, default: False): when true, select the certified sizing n = \gamma m \log(m) and independent Christoffel draws.

  • ChristoffelSubsampleExperiment-Gamma (Scalar, default: 9.242343873386666): constant \gamma of the certified sizing. It must be finite and strictly positive when the certified mode is selected.

  • ChristoffelSubsampleExperiment-MaxAttempts (UnsignedInteger, default: 10): maximum number of independent certified draws tried before the draw with the largest smallest Gram eigenvalue is returned with a frame warning.

  • ChristoffelSubsampleExperiment-MaxProjectionAttempts (UnsignedInteger, default: 1000000): maximum number of Christoffel proposals tried to draw one admissible projection DPP point before an error is raised. It only guards against a pathological numerical failure.

Examples

>>> import openturns as ot
>>> import openturns.experimental as otexp
>>> ot.RandomGenerator.SetSeed(0)
>>> factory = ot.OrthogonalProductPolynomialFactory([ot.Uniform(-1.0, 1.0)])
>>> basis = ot.OrthogonalBasis(factory)
>>> experiment = otexp.ChristoffelSubsampleExperiment(basis, 60)
>>> print(experiment.getSpaceDimension())
60
>>> sample, weights = experiment.generateWithWeights()
>>> print(len(sample), len(weights))
60 60
__init__(*args)
static DeduceSpaceDimension(size)

Deduce the space dimension from a target size.

In the default mode the dimension is the target size (k = 0 in m = n - k). With a finite basis, the constructor builds functions until the basis is exhausted and keeps the largest available dimension. With m = n the projection DPP is sampled sequentially, so keep the target size moderate.

When ChristoffelSubsampleExperiment-Certified is true, the result is the largest m \ge 1 such that \gamma m \log(m) \le n, with \gamma read from ChristoffelSubsampleExperiment-Gamma. The basis capacity is still applied by the constructor.

Parameters:
sizepositive int

Target number of points.

Returns:
spaceDimensionpositive int

The target size in the default mode, or the certified dimension m when the certified mode is selected.

computeDesignEigenvalues(sample, weights)

Eigenvalues of the weighted design Gramian.

Parameters:
sample2-d sequence of float

Design points.

weightssequence of float

Positive finite weight of each design point.

Returns:
eigenvaluesPoint

Eigenvalues of the mean over the design of weight times outer product, the frame stability certificate.

Notes

The weights must be positive and finite; a zero-weight design point is rejected because the frame certificate would silently ignore it.

generate()

Generate points according to the type of the experiment.

Returns:
sampleSample

Points (\inputReal_i)_{i = 1, ..., \sampleSize} of the design of experiments. The sampling method is defined by the type of the weighted experiment.

Examples

>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> myExperiment = ot.MonteCarloExperiment(ot.Normal(2), 5)
>>> sample = myExperiment.generate()
>>> print(sample)
    [ X0        X1        ]
0 : [  0.608202 -1.26617  ]
1 : [ -0.438266  1.20548  ]
2 : [ -2.18139   0.350042 ]
3 : [ -0.355007  1.43725  ]
4 : [  0.810668  0.793156 ]
generateWithWeights(*args)

Generate the weighted design.

Parameters:
suppliedSample2-d sequence of float, optional

Supplied candidate points, assumed to be draws from the reference measure, e.g. already evaluated points to recycle. An empty sample, whatever its dimension, selects the fresh path. With more than size points, exactly size of them are selected by exact volume sampling. With exactly size points, all of them are returned unchanged with unit weights. With fewer than size and at most spaceDimension points, all of them are kept and the design is completed by a conditional projection DPP, plus independent Christoffel points when size exceeds the space dimension. More than spaceDimension supplied points while asking for fewer than size points is rejected. In certified mode, a non-empty supplied sample is rejected: only independent Christoffel draws carry the certificate.

Returns:
sampleSample

The design of size points.

weightsPoint

The associated importance weights.

getClassName()

Accessor to the object’s name.

Returns:
class_namestr

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

getDistribution()

Accessor to the distribution.

Returns:
distributionDistribution

Distribution of the input random vector.

getName()

Accessor to the object’s name.

Returns:
namestr

The name of the object.

getOrthogonalBasis()

Accessor to the orthogonal basis.

Returns:
basisOrthogonalBasis

Orthogonal basis defining the approximation space.

getSize()

Accessor to the size of the generated sample.

Returns:
sizepositive int

Number \sampleSize of points constituting the design of experiments.

getSpaceDimension()

Accessor to the space dimension deduced from the target size.

Returns:
spaceDimensionpositive int

Number of leading basis functions used.

hasName()

Test if the object is named.

Returns:
hasNamebool

True if the name is not empty.

hasUniformWeights()

Ask whether the experiment has uniform weights.

Returns:
hasUniformWeightsbool

Whether the experiment has uniform weights.

isRandom()

Accessor to the randomness of quadrature.

Parameters:
isRandombool

Is true if the design of experiments is random. Otherwise, the design of experiment is assumed to be deterministic.

setDistribution(distribution)

Accessor to the distribution.

Parameters:
distributionDistribution

Distribution of the input random vector.

setLevels(levels)

Accessor to the experiment nesting levels.

Parameters:
levelssequence of int

Nesting level for each component.

setName(name)

Accessor to the object’s name.

Parameters:
namestr

The name of the object.

setOrthogonalBasis(basis)

Accessor to the orthogonal basis.

Parameters:
basisOrthogonalBasis

Orthogonal basis defining the approximation space. Its embedded measure \mu must be continuous.

Notes

The space dimension and the Christoffel distribution are deduced again from the new basis and the current size.

setSize(size)

Accessor to the size of the generated sample.

Parameters:
sizepositive int

Number \sampleSize of points constituting the design of experiments.

Examples using the class

Christoffel subsampling for the Ishigami function

Christoffel subsampling for the Ishigami function

Christoffel subsampling on the square

Christoffel subsampling on the square