UxHw® API Conventions

This page describes conventions that apply across the whole UxHw API, rather than to any single function.

API naming convention

The API function names follow a {namespace}{adverb}{verb} or {namespace}{adjective}{noun} format. Each API function begins with the namespace prefix UxHw. This is followed by the additional namespace classifier Float or Double. The final part of the API function name is a verb or noun which indicates the main action (verb) or the main property (noun) (e.g., the verb Sample in UxHwFloatSample and the noun DistFromMultidimensionalSamples in UxHwFloatDistFromMultidimensionalSamples).

Distributional and particle values of UxHw distributions

On architectures that associate distributional information with floating-point values, we refer to the associated distributional information as a distributional value, to the floating-point value itself as a particle value, and to the combination of the two as a UxHw distribution (or just distribution). Whenever a UxHw function generates a new distribution, we set the particle value of the distribution equal to the mean value of the distribution.

When a function $f$ is applied to a distribution $A$, we compute the particle value of the distribution $f(A)$ by applying $f$ to the particle value of $A$. Since $E[f(A)]$ is not, in general, equal to $f(E[A])$ when $f$ is nonlinear, the particle value of $f(A)$ will not necessarily be equal to the mean value of the distributional value of $f(A)$. This means that after computations, the particle value of a UxHw distribution is not always equal to the mean value of its distributional value.

Handling of NaN

The UxHw API generally treats NaN as an unrecoverable input. A UxHw function abandons the call when a control argument is NaN, or when a distributional value argument is a NaN particle value with no distribution associated with it. The function then writes a diagnostic message to the standard error stream of your application and returns -NaN:

UxHw(Float|Double)Quantile: probability is NaN. Returning ...

The returned -NaN is a particle value only, without a distributional value.

Test the result with isnan(). The negative sign marks a value that the API rejected, rather than one your own computation produced, but IEEE 754 does not preserve the sign of NaN through arithmetic, so the sign is meaningful only on the value the function returns.

Arithmetic is the exception. Operating a distributional value with a NaN particle value produces NaN and writes no diagnostic message, because that is the result IEEE 754 arithmetic already produces.

A distribution can also carry probability mass at NaN, which records the fraction of the distribution that is unusable. UxHwDoubleSample() returns NaN with a probability equal to that fraction, and probability queries account only for the usable mass. UxHwDoubleProbabilityGT(value, cutoff) and the complementary probability that value is less than or equal to cutoff therefore sum to one minus the NaN mass, rather than to one.