ZIO Tensors

In some cases, we want to easily send tensors between components. We want to do this simply and generally so that disparate endpoints can communicate without knowing details of each other but so that tensors may be faithfully transmitted. The requirements, needs and allowances are:

• no tensor operations provided
• faithfully transmit tensor
• minimize memory copy both internally and at the interface with application code.
• allow for possible compression and/or sparse representation
• support multiple tensors per message
• allow spreading single tensor across message
• allow association of application metadata
• allow other message forms to coexist with tensor message forms.

Thus, at a minimum the message representation shall include:

• conceptual tensor metadata (eg, rank, shape, element type)
• memory layout metadata (order, compression, sparseness)
• the packed tensor element data itself
• indexing of one tensor in a larger set of tensors
• means to associate application metadata to tensors.

The ZIO TENS message format attempts to provide the above requirements. A TENS message may have a ZIO message form header value of TENS however, an application may choose to include the general TENS form in other messages as long as the rest of the specification is followed. A compatible form is FLOW (which requires the form to be FLOW).

As with other forms, the zio::Message header prefix attribute label shall hold structured data as an object encoded as a JSON string. A TENS message may utilize zero or more parts of the zio::Message payload to hold packed arrays of elements, one for each given tensor.

The label object shall have a top-level attribute key TENS which holds all information required to reconstitute the tensors stored in the message except the element data itself.

The value of the TENS object shall have two attributes. Expressed as JSON they are:

{
  "TENS": {
    "tensors": [ ... ],
    "metadata": { ... },
   }
}

Application may extend a TENS message form in a number of ways:

• The four byte message form may be other than TENS.
• the label object may have additional attributes besides TENS.
• the TENS JSON object may be extended by novel keys other than the reserved keys listed above. Note the TENS.tensors array may not be extended.
• message payload parts other than those referenced by TENS.tensors[].part attribute may be used for purposes other than TENS.

The specification above defines a TENS message. The zio/tens.hpp C++ API provides some support for handling TENS messages. See test/test_tens.cpp in the ZIO source for an example of this API being exercised.

As said above, the TENS message form is sympathetic with Boost Multi Array (manual and reference). ZIO does not provide tests against Boost in order to minimize dependency but an application may try something like the following to cast a TENS part into a Boost MA:

zio::Message msg;
const zio::message_t& data = zio::tens::at(msg, 0);
auto tens = msg.label_object()["TENS"]["tensors"][0];
auto shape = tens["shape"];
assert(shape.size() == 3);
const float* fdata = (const float*)data.data();
const size_t n1=shape[0].get<size_t>();
const size_t n2=shape[1].get<size_t>();
const size_t n3=shape[2].get<size_t>();
boost::const_multi_array<float, 3> tensor(fdata, boost::extents[n1][n2][n3]);

And, likewise one can fill a message part with something like:

zio::Message msg;
std::vector<size_t> shape={n1,n2,n3};
zio::tens::append(msg, tensor.data(), shape);