Skip to main content

Distribution to Ux Binary Data

Introduction​

Embedded systems like Signaloid C0-microSD can not output Ux Data in an ASCII-formatted version (e.g., they do not support the printf family of functions). For such cases, the UxHw API allows you to output the Ux Binary, i.e., the binary representation of the distributional information associated with a source-code variable.

The Format of Ux Data: Ux Binary​

The format of Ux Binary data is:

  1. Particle value (32 bits for float or 64 bits for double)
  2. Representation type (8 bits).
  3. Number of samples (64 bits).
  4. Mean value of distribution (64 bits).
  5. Number of non-zero mass Dirac deltas (32 bits).
  6. A sequence of n pairs of (a) support position (64 bits); (b) probability mass (64 bits).

Name​

UxHwDoubleDistributionToByteArray, UxHwFloatDistributionToByteArray — Convert a distributional value to an array of bytes.

Synopsis​

#include <stddef.h>
#include <uxhw.h>

ssize_t UxHwDoubleDistributionToByteArray(double value, uint8_t *  destByteBuffer, size_t destByteBufferSizeInBytes);
ssize_t UxHwFloatDistributionToByteArray(float value, uint8_t *  destByteBuffer, size_t destByteBufferSizeInBytes);

Description​

On architectures that associate distributional information with floating-point values, the UxHwDoubleDistributionToByteArray() function stores the Ux Binary data associated with source variable value in the destByteBuffer unsigned byte array. The destByteBufferSizeInBytes source parameter is the size of the destByteBuffer in bytes and the UxHw API uses it to determine if there is enough space in destByteBuffer for safe storage of the Ux Binary data associated with value. For determining the minimum required size of destByteBuffer for being able to store the distribution associated with value you can use the UxHwDoubleGetSizeOfDistributionByteArrayInBytes function (see here). The returned value of the function is the number of bytes written in destByteBuffer.

Parameters​

  • value — The distributional value whose Ux Binary data will be exported.
  • destByteBuffer — The destination array of unsigned bytes that the Ux Binary data of value will be stored in.
  • destByteBufferSizeInBytes — The size of destByteBuffer in bytes.

Return Values​

The UxHwDoubleDistributionToByteArray() function returns the amount of data written in destByteBuffer or -1 in case of failure.

✏️   Examples​

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <uxhw.h>

int
main(void)
{
    /*
     *  Example where we initialize `value` as a Uniform distribution.
     *  The same steps apply for any distribution associated with `value`,
     *  whether parametric or empirical.
     */
    double      value = UxHwDoubleUniformDist(0.1, 1.0);
    /*
     *  Get the minimum number of bytes that you need to store the Ux Binary
     *  data of `value`.
     */
    size_t      destByteBufferSizeInBytes = UxHwDoubleGetSizeOfDistributionByteArrayInBytes(value);
    uint8_t *   destByteBuffer;
    ssize_t     destByteBufferWrittenInBytes;

    destByteBuffer = (uint8_t *) calloc(destByteBufferSizeInBytes, sizeof(uint8_t));
    if (destByteBuffer == NULL)
    {
        printf("Memory allocation for `destByteBuffer` failed. Exiting.\n");

        return 1;
    }

    destByteBufferWrittenInBytes = UxHwDoubleDistributionToByteArray(value, destByteBuffer, destByteBufferSizeInBytes);

    if (destByteBufferWrittenInBytes < 0)
    {
        printf("Writing to destination byte buffer failed.\n");
        free(destByteBuffer);

        return 1;
    }

    printf("Wrote %zd bytes of Ux Binary data of `value` in `destByteBuffer`.\n", destByteBufferWrittenInBytes);
    
    free(destByteBuffer);

    return 0;
}
Last updated on