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).

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 with no distribution associated with it:

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

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.