Skip to main content

Returning Results to the Host

Each recipe on this page writes a result into the output buffer on the module, and shows how the host application reads it back. The Cookbook conventions define the compute_module object, the round trip, and the buffer capacities that the snippets rely on. In every recipe, result is a distributional float that your device application has already computed.

caution

With debug logging enabled, the log window occupies the last 512 bytes of the output buffer, so a full-width result would overwrite it. See Buffer Capacities.

Return the particle value as a plain float​

Writing a distributional float into the output buffer as an ordinary float returns its particle value, the single number the computation would have produced on conventional hardware. Use this when the host only needs the point result.

On the module

#include "C0HAL.h"

kC0HALOutputBufferFloat[0] = result;

On the host

import struct

output = compute_module.calculate_command(1, poll_sleep_time=0.001, verbose=False)
(particle_value,) = struct.unpack("<f", output[:4])

Return on-module statistics as plain floats​

The device application reduces the distribution to the statistics the host cares about, and returns them as plain floats. Use this when the host needs a few summary numbers rather than the distribution itself.

On the module

#include <uxhw.h>
#include "C0HAL.h"

kC0HALOutputBufferFloat[0] = UxHwFloatNthMoment(result, 1);		/* mean */
kC0HALOutputBufferFloat[1] = UxHwFloatNthMoment(result, 2);		/* variance */
kC0HALOutputBufferFloat[2] = UxHwFloatProbabilityGT(result, 10.0f);	/* tail probability */

On the host

import struct

output = compute_module.calculate_command(1, poll_sleep_time=0.001, verbose=False)
mean, variance, tail_probability = struct.unpack("<3f", output[:12])

The querying API offers more reductions in the same shape, including the nth mode with UxHwFloatNthMode() and the support bounds with UxHwFloatSupportMin() and UxHwFloatSupportMax(). See Nth Centralized Moment of a Distribution, Tail Probability, and the Querying Uncertainty Information index.

Return samples from a distributional value​

The device application draws random samples from the distribution and returns them as a float array. Use this to feed host-side code that expects Monte-Carlo-style samples.

On the module

#include <uxhw.h>
#include "C0HAL.h"

uint32_t sampleCount = kC0HALInputBufferUint32[0];

UxHwFloatSampleBatch(result, (float *) kC0HALOutputBufferFloat, sampleCount);

On the host

import struct

sample_count = 100
compute_module.write_input_buffer(struct.pack("<I", sample_count))
output = compute_module.calculate_command(2, poll_sleep_time=0.001, verbose=False)
samples = struct.unpack(f"<{sample_count}f", output[: 4 * sample_count])

The output buffer holds up to 1024 samples on the C0-microSD and 8192 on the C0-microSD+, less 128 samples in builds with debug logging enabled. See Batch sampling from a Distribution.

Return the full distribution as Ux Binary data​

The device application serializes the whole distribution, so the host receives everything, not a summary. Use this whenever the host will print, plot, store, or further analyze the result. See Using the Results on the Host for that half.

On the module

A 4-byte length header tells the host how many payload bytes follow.

#include <uxhw.h>
#include "C0HAL.h"

kC0HALOutputBufferUint32[0] = UxHwFloatDistributionToByteArray(
	result,
	(uint8_t *) &kC0HALOutputBufferUint32[1],
	kC0HALOutputBufferUint8Length - sizeof(uint32_t));

On the host

import struct
from signaloid.distributional.distributional import DistributionalValue

output = compute_module.calculate_command(1, poll_sleep_time=0.001, verbose=False)
(payload_size,) = struct.unpack("<I", output[:4])
dist = DistributionalValue.parse(output[4 : 4 + payload_size])

UxHwFloatGetSizeOfDistributionByteArrayInBytes() reports the exact serialized size before you write, which matters when one buffer carries several values. See Distribution to Ux Binary Data and Size of Byte Array for Storing Ux Binary Data.

Next steps​

Last updated on