Purpose

The module Histogram3DInterpolationPolynomial computes (an approximation to) a histogram of a multivariate interpolation polynomial with values in a three-dimensional space (represented as three scalar-valued multivariate polynomials).

Be sure not to confuse the dimension of the pre-image space (which is arbitrarily high here as for all the * InterpolationPolynomial modules) with the dimension of the image space (which is 3 here but only 1 for most other * InterpolationPolynomial modules). Since the modules that create multivariate interpolation polynomials do not support that, we need three polynomials as input.

Windows

Default Panel

../../../Modules/ML/MLStochasticCollocation/mhelp/Images/Screenshots/Histogram3DInterpolationPolynomial._default.png

Input Fields

Connect here the polynomials to be examined. The module only works if all three inputs are fed.

However, if you want to compute a histogram of a 1D or 2D valued polynomial, connect a zero polynomial to the other inputs (using the TensorInterpolationPolynomial module with Nodes=Values=0). However, this workaround will most probably not work with the 'sophisticated algorithm', see below.

A Histogram3DInterpolationPolynomial module might be included in the project later to serve this purpose.

inputPolynomial1

name: inputPolynomial1, type: MLBase

inputPolynomial2

name: inputPolynomial2, type: MLBase

inputPolynomial3

name: inputPolynomial3, type: MLBase

Output Fields

output0

name: output0, type: Image

Contains the histogram as a 3D image.

Parameter Fields

Visible Fields

Bounding Box Polynomial 1

name: autoBBox1, type: String, persistent: no

Shows the generic bounding box of the first polynomial.

It can also be obtained with an EvaluateInterpolationPolynomial module. This is a bounding box in the pre-image space.

Bounding Box Polynomial 2

name: autoBBox2, type: String, persistent: no

Shows the generic bounding box of the second polynomial.

It can also be obtained with an EvaluateInterpolationPolynomial module. This is a bounding box in the pre-image space.

Bounding Box Polynomial 3

name: autoBBox3, type: String, persistent: no

Shows the generic bounding box of the third polynomial.

It can also be obtained with an EvaluateInterpolationPolynomial module. This is a bounding box in the pre-image space.

Bounding Box Selection

name: bBoxSelection, type: Enum, default: Union

Sets whether the generic bounding box of one of the three polynomials or (the convex hull of) their union or a manually entered bounding box is used.

The module needs a bounding box in the pre-image space. The polynomial is restricted to this set before the histogram is computed. Since this set is compact, the range of the polynomial will then also be compact, hence bounded. (The range of the polynomial on this set is also referred as the bounding box in image space.)

Values:

Title Name
Manual Manual
Polynomial 1 Polynomial 1
Polynomial 2 Polynomial 2
Polynomial 3 Polynomial 3
Union Union

Manual Bounding Box

name: manBBox, type: String

Sets a pre-image bounding box manually.

To be used, the Bounding Box Selection needs to be set to Manual.

Use manual image bounding box

name: useManImageBBox, type: Bool, default: TRUE

If checked, an image bounding box can be entered manually.

Manual Image Bounding Box

name: manImageBBox, type: String

Sets an image bounding box and it determines the size of the output ML image.

If Use manual image bounding box is set to false, the generic bounding box is used here, which is defined as the (cuboid shaped hull of) the compact set of values that the polynomial takes on the selected pre-image space bounding box.

However, using this automatic value is slower than entering a manual bounding box. Hence it is recommended to enable this switch and enter a sensible manual bounding box.

The behavior of the module in the case that the manual bounding box is too small can be influenced using the Project to bounding box field, but not for the 'sophisticated algorithm'.

Use sophisticated algorithm

name: sophisticatedAlgorithm, type: Bool, default: FALSE

If checked, a different algorithm is used to compute the histogram.

This algorithm is similar to the one employed in the (one-dimensional) HistogramInterpolationPolynomial module, however the advantage is not so clear for this case. The sophisticated algorithm is supposed to give better results for the same Histogram Accuracy but, on the other hand, will be considerably slower. Which of the two algorithms gives the better result with comparable computational effort, may depend on the concrete example.

Note that some of the fields below only matter for one of the two algorithms: The Epsilon to Avoid Division by Zero and Maximal Summand to Avoid Cancellation fields only matters for the sophisticated algorithm, the Project to bounding box field only matters for the standard algorithm.

Histogram Accuracy

name: accuracy, type: Integer, default: 20, minimum: 2

Sets the number of points per space dimension in which the pre-image bounding box is scanned.

The higher the number, the better is the approximation of the histogram, but the slower is the computation.

Image Voxel Size

name: voxelSize, type: Vector3, default: 1 1 1

Sets the voxel size of the output ML image and thus also the quality of the histogram.

This does not influence the performance so much as the Histogram Accuracy field.

Convert meters

name: convertMeters, type: Bool, default: TRUE

If checked, the module will assume that the polynomials' values have the unit of meters and should be converted to millimeters in the ML image (as is usual for the ML).

In this case, the Image Voxel Size is interpreted as millimeters as well, whereas the Manual Image Bounding Box is interpreted as meters. If you find this too confusing, disable this field, so that no conversions are performed.

Compute on demand

name: computeOnDemand, type: Bool, default: FALSE

If checked, the module computes on demand.

It is well-known that the ML uses a page-based image processing technique. However, for this module, this is in general unsuited since it would reduce the performance. Hence, this module usually computes the complete output ML image as soon as the first page is requested. However, if you configure the module to yield a very large output image, this could lead to a memory shortage. In this case, you can enable this field. It will solve the memory problem but slow down the computation considerably.

Project to bounding box

name: projectToBBox, type: Bool, default: TRUE

Sets the behavior of the module in the case that the manually chosen image bounding box is too small.

If disabled, the histogram is just cut off, resulting in an image that does not integrate to one (as it otherwise does). If enabled (which is the default), the values that lie outside are projected to the nearest point inside. The image will then always integrate to one, but where appropriate have noticeably high values on the boundary of the ROI.

This field does not work if the field Use sophisticated algorithm is enabled; the histogram is then always cut off.

Epsilon to Avoid Division by Zero

name: eps, type: Double, default: 1e-10, minimum: 0

Sets an epsilon value to avoid a division by zero.

In the computation procedure, some divisions have to be performed where the denominator might be zero. This corresponds to the fact that a histogram can have infinitely high peaks. To avoid problems, the (small) value entered in this field is added to the denominator before the division. The smaller the number, the better is the approximation of the histogram. 0 is allowed but not recommended, except possibly if you are sure that the polynomial has no critical points within the specified bounding box.

This field only matters if the field Use sophisticated algorithm is enabled.

Maximal Summand to Avoid Cancellation

name: maxSummand, type: Double, default: 1000000, minimum: 0

Sets a maximal summand value to avoid cancellation problems.

If the histogram has large peaks, the sophisticated algorithm in its current implementation suffers from some cancellation problem. This will result in large, cuboid shaped areas of the image being filled with strange, wrong values. A workaround is to limit the value of each summand using this field. This changes the height of the peaks, of course, but for most applications this is not important.

If the value is too large, the mentioned cancellation problem occurs. If the value is too small, it affects also the histogram values away from the peaks. A good choice is to use about 100 or 1000 times the largest histogram value away from the peaks.

This field only matters if the field Use sophisticated algorithm is enabled.

Simplify polynomials

name: simplifyPolynomials, type: Bool, default: FALSE

If checked, the polynomials will be simplified first.

The same procedure is used by the module SimplifyInterpolationPolynomial.

This may either speed up or slow down the computation, depending on the polynomial and on the settings.

Note that simplifying a polynomial destroys the bounding box information, but that does not matter since this module evaluates the bounding boxes before simplifying.