ChristoffelSubsampleExperiment¶
(Source code, 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.experimentalsubmodule.Given an orthonormal basis of
and a target size
, the experiment builds the first
basis functions and returns a weighted design of
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
are the density ratios of the reference measure over the Christoffel distribution, so the weighted design is an unbiased quadrature rule for
. 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,
is the largest dimension supplied by the basis:
with an inexhaustible basis, and
is tried until the basis supplies
functions. For
, a fresh design is an exact projection DPP of size
associated with the Christoffel kernel. For
, the first
points are a projection DPP and the remaining
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-Certifiedkey is true, the experiment uses the certified sizing of Cohen and Dolbeault [cohendolbeault2020]:is the largest integer with
, where
is the
ChristoffelSubsampleExperiment-Gammakey value, and a fresh design isindependent 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 toChristoffelSubsampleExperiment-MaxAttemptsdraws. 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 makesmuch smaller than
and is not the default; when the key is false,
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
and adapts
. It is natural when the approximation space belongs to a nested hierarchy, but not when
is fixed by the model and only
can be chosen. In that fixed-space setting the certificate gives the lower bound
for the fixed
; the current implementation does not expose a fixed-
strategy, which is left for a future release. As a workaround, choose the target size
for
(and
for
), provided the basis supplies
functions and
. For small
the formula can give
, in which case the certified space dimension is bounded by
; check
getSpaceDimension()and increase(or
) until it is
.
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 thanpoints are supplied, exactly
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
this selection is the projection-DPP law restricted to the pool, and when
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
ratios are not guaranteed unbiased quadrature weights for
. If exactly
points are supplied, all of them are kept with unit weights, since no Christoffel selection takes place. If fewer than
and at most
points are supplied, all of them are kept and the DPP is conditioned on their feature vectors; the remaining
DPP points are drawn, followed by
independent Christoffel points when
. Supplying more than
points while asking for fewer than
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
, the density ratio of the reference measure over the Christoffel distribution. The exactly-
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
, where
is the
ChristoffelSubsampleExperiment-FrameTolerancekey, and warns when they are missed. In the default mode this check is advisory: it is not a certificate that the frame bounds hold. Forthe design is square and the projection DPP has no certified frame guarantee; for
the extra independent Christoffel points improve the budget without making the certificate exact. In certified mode, the independent Christoffel budget
is the leading-order Cohen-Dolbeault setting; the omitted
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:
- basis
OrthogonalBasis Orthonormal basis defining the approximation space. Its embedded measure
must be continuous.
- sizepositive int
Number
of points of the experiment.
- basis
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.
Accessor to the object's name.
Accessor to the distribution.
getName()Accessor to the object's name.
Accessor to the orthogonal basis.
getSize()Accessor to the size of the generated sample.
Accessor to the space dimension deduced from the target size.
hasName()Test if the object is named.
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 optionallysetSize()) before generating. Generation from the unconfigured default state throws.The following
ResourceMapkeys 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 sizingand independent Christoffel draws.
ChristoffelSubsampleExperiment-Gamma(Scalar, default:9.242343873386666): constantof 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 (
in
). With a finite basis, the constructor builds functions until the basis is exhausted and keeps the largest available dimension. With
the projection DPP is sampled sequentially, so keep the target size moderate.
When
ChristoffelSubsampleExperiment-Certifiedis true, the result is the largestsuch that
, with
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
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:
- eigenvalues
Point Eigenvalues of the mean over the design of weight times outer product, the frame stability certificate.
- eigenvalues
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:
- sample
Sample Points
of the design of experiments. The sampling method is defined by the type of the weighted experiment.
- sample
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
sizepoints, exactlysizeof them are selected by exact volume sampling. With exactlysizepoints, all of them are returned unchanged with unit weights. With fewer thansizeand at mostspaceDimensionpoints, all of them are kept and the design is completed by a conditional projection DPP, plus independent Christoffel points whensizeexceeds the space dimension. More thanspaceDimensionsupplied points while asking for fewer thansizepoints is rejected. In certified mode, a non-empty supplied sample is rejected: only independent Christoffel draws carry the certificate.
- Returns:
- getClassName()¶
Accessor to the object’s name.
- Returns:
- class_namestr
The object class name (object.__class__.__name__).
- getDistribution()¶
Accessor to the distribution.
- Returns:
- distribution
Distribution Distribution of the input random vector.
- distribution
- getName()¶
Accessor to the object’s name.
- Returns:
- namestr
The name of the object.
- getOrthogonalBasis()¶
Accessor to the orthogonal basis.
- Returns:
- basis
OrthogonalBasis Orthogonal basis defining the approximation space.
- basis
- getSize()¶
Accessor to the size of the generated sample.
- Returns:
- sizepositive int
Number
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:
- distribution
Distribution Distribution of the input random vector.
- distribution
- 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:
- basis
OrthogonalBasis Orthogonal basis defining the approximation space. Its embedded measure
must be continuous.
- basis
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
of points constituting the design of experiments.
OpenTURNS